For Developers‎ > ‎Design Documents‎ > ‎

UI Localization (aka Translations)

If you find an error in an existing translation, please file a bug using the translation template.  CC "chromelocalization@google.com".  Thank you!
You can also help provide translations for the chromium-browser package on Ubuntu.

How to add a string

  1. Add the string to the grd file (generated_resources.grd, webkit_strings.grd, chromium_strings.grd or google_chrome_strings.grd).  See below in the "Overview of files" section for guidance on which file to add the string to.
  2. **Very important info on writing good message descriptions - see section below.
  3. Surround the string with an appropriate <if> clause to ensure that it's only included it on platforms where it's actually used (e.g. Mac and Linux). Strings used on all platforms can omit the <if> clause.
  4. The next time you build the solution, this will automatically add the en-US string to en-US.dll.
  5. In your code, include ui/base/l10n/l10n_util.h and grit/generated_resources.h.
  6. To get the string, use l10n_util::GetStringUTF16.  Alternately, you can use l10n_util::GetStringFUTF16 which will replace placeholders $1 through $4 with the extra arguments of GetStringFUTF16.  Note that we generally prefer to use UTF-16 encoded strings for user-visible text.

How to add an Android/Java string

  1. Add the string to the grd file in the Java folder (e.g. content/public/android/java/strings/android_content_strings.grd).  Strings should be named in all caps with the prefix IDS_.  For example: IDS_MY_STRING.
  2. **Very important info on writing good message descriptions - see section below.
  3. At build time, an Android-style strings.xml file will be generated in the out directory.
  4. You can reference these strings in Java code using the standard R.string.my_string syntax, or in Android layouts using @string/my_string.  Note: the name is lowercase and the IDS_ prefix is stripped.
If you are contributing code to the Google Chrome version of Chromium, then this is all you need to do.  The process of translating the string from en-US to the other languages will be handled by Google's translation team.

If you are adding a string to Chromium that you want for a different version of Chromium and you want to have translation in other languages, you need to add translations to the .xtb files in /src/chrome/app/resources.  These files have a translation id that is based on a hash of the en-US string (see /src/tools/grit/grit/extern/FP.py for details on the hash).

How to add a new grd(p) file

  • This should be rare. We want to be very careful about expanding the number of grd(p) files in our source tree.
  • New grdp files need to be referenced from a parent grd file.
  • If your new grd(p) will result in new XTB files after translation, you must commit empty/shell placeholder .xtb files.  Or your translations will never appear back in Chromium.

Overview of files

/src/chrome/app/generated_resources.grd
/src/webkit/glue/webkit_strings.grd
  Strings for the main UI language (en-US) get added to these files.  If the string is used in webkit (i.e., shows up in content), then add the string to webkit_strings.grd.  Otherwise, add the string to generated_resources.grd.  These grd files are the "pivot" format on which everything else is based.

* You may see .grdp files in the source tree as well.  These are grd parts.  Basically a parent grd file will be referencing and including these sub files. 

/src/chrome/app/resources/*.xtb
/src/webkit/glue/resources/*.xtb
  These files contain translations in each language of the en-US strings in the grd files.

/src/tools/grit/
  GRIT (Google Resource and Internationalization Tool) is a script that that runs during the build that combines the grd files with the xtb files to generate a C++ header file with string IDs and a Windows resource file (.rc) containing the strings.

/src/chrome/app/chromium_strings.grd
/src/chrome/app/google_chrome_strings.grd
  Similar to the generated_resources.grd and webkit_strings.grd but these files allow for having strings that refer to Google Chrome vs Chromium.  These files should define strings for the same IDs, they just have different translations.  Visual Studio will build the correct file based on an environment variable.

/src/chrome/app/resources/locale_settings.grd
  This file contains values that vary by locale, but are not sent to translators (i.e., they are used by developers).  For example, the default font size depends on locale, so we put it in this file.  We put the en-US value in locale_settings.grd and for all other locales, we put values in the locale_settings*.xtb files.  You must provide a value for all locales for the grd file to build properly.

/src/chrome/tools/check_grd_for_unused_strings.py
   Tool that tries to find unused strings. This tool does not currently take <if> statements into consideration.

Workflow for how strings get translated for Google Chrome

  1. Strings get added to a grd file
  2. [BlackCloudOfMagic] Translators are provided with the new strings
  3. <internal link> Further internal detail about this semi-automated process here.  </internal link>
  4. [BlackCloudOfMagic] Translations are created and dumped to xtb files
  5. Changes to xtb files are checked into the Chromium source tree

Caveats

    Strings are included on all platforms by default and will needlessly increase the download size if not used.  It's important to judiciously surround strings with an appropriate <if> clauses  to ensure that they are only included on the platforms where they're actually used.



Writing good message descriptions


The message description added to the grd(p) file with your string is currently the only context our translators receive when translating UI strings.  We would all like to do our best to ensure that the user experience with Chromium is as natural as possible, no matter the language.  So let's try to give the translators as much clear context as possible.  The following includes what information is needed in a good description, placeholder information, max chars limit, as well as some examples of what these should look like.

IE: (The translator would only see what is in bold)

<message name="IDS_BOOKMARK_BUBBLE_PAGE_BOOKMARKED" desc="In Title Case: Title of the bubble after bookmarking a page.">
    Bookmark Added!
</message>

(NOTE: Translators also see "meaning" if added to a message, but we only want to use this in special cases where there are duplicate identical source messages - but they have different contexts/restrictions, so we want them translated separately.)

Why do we need message descriptions?


The problem
: Currently, the translators often have no context when they translate -- they see each string in isolation and in random order, so they don't even know which feature it could be associated with, where it might appear on a page, or what action it triggers. Without context, they can't know how to translate appropriately.

The solution
: Message descriptions can help provide context and other essential information, which in turn increases the speed, accuracy, and quality of translations, and, ultimately, improves user satisfaction.


What information should I provide in the message description?

  • Where is the text located? (e.g., button, title, link, pull-down menu)
  • What triggers the message and/or what is the result? What page or text comes before and after?
  • What do the placeholders stand for? Will this message replace a placeholder in another message? Do they need to be arranged in a certain way?
  • Is this a verb or a noun? If an adjective, what does it refer to?
  • Who is the message intended for?
  • Are there any specific character limits that must not be exceeded? (e.g., for mobile products where UI space is restricted)
How should line breaks be dealt with? Are there character limitations per line? Keep in mind that the translators will not know the product as well as you do, and they work on multiple products and projects. Also, they're not engineers. So make sure that the description will be understandable by a more general audience and doesn't contain too much technical detail. Imagine giving this description out of context to a person not on your project, say your Aunt. Would they still understand it?

What does this look like in practice?


Source Message: "US city or zip"
Original Description: The message is shown in gray in the empty search box for a movie showtimes location. The content of the message should be localized by country to mean city or postal code (or simply city). Its purpose is to tell the user what kind of input will produce results.
Comment: This is very informative description, that clearly explains the context and also gives specific instructions on how the message should be adapted for another (non-US) locale.

Source Message: "Apply"
Original Description: Button label for the apply button.
Comment: Provides the context, but the translator will also need to know what is going to be applied.
Better Description: Button label; clicking the button will apply the selected label names to the message thread.

Source Message: "read Gmail attachment previews"
Original Description: Displayed in the Settings panel which lists the various permissions that this app requires. Must start with a lowercase.
Comment: Providing the translators with instructions is good, but they also need to know the reason. Why does this need to be lowercase? Different languages have different conventions around capitalization, so we need to know the reason behind the instruction. Also, what is the context? Will any text come before or after?
Better Description: Displayed in the Settings panel which lists the various permissions that this app requires. Should start with a lowercase because it will be listed with other permissions, all separated by a comma.

Source Message: "Zoom"
Original Description: The "Zoom" menu command. It brings up help on how to zoom. Try to limit menu commands to 10 characters.
Comment: Very nice description in Mobile Maps. Tells us what it does, what it triggers and what the character limit should be to keep consistency across similar messages.

Source Message: "We could not send your message. A space alien ate it. Please try again in a few minutes."
Comment: Should we translate the "space alien" part, or should it be changed to an appropriate equivalent for that locale? Should it be funny? By default, the translators will probably translate the message literally, so if they should get creative, the message description should let them know that.
Better Description: An error message. This reason given is meant to be funny, so please use an appropriate silly reason for the error, and not necessarily a direct translation.

Subpages (1): Mac Notes
Comments