Skip to content

Latest commit

 

History

History
128 lines (90 loc) · 6.23 KB

l10n.md

File metadata and controls

128 lines (90 loc) · 6.23 KB
Raw

Localization L10N

Our localization team uses Transifex to maintain all translatable strings. We have a hook that synchronizes Transifex with localization files in our version control systems. As a developer, you should ideally be able to use the localization framework that best fits your needs. For the hook to work, though, you must tell it about your localization files.

Our hook requires your strings to live in separate files per language. The source language is English with sublanguage German (EN_de), which stands for developer English.

Localization file formats we support include: Java properties, GWT properties, Ember L10N, the legacy Acrolinx All Strings XML format, and more. (See Confluence for the full list of file formats we support.) Note that we don't necessarily support all formats that Transifex supports. Please only use file formats from that list or open a Jira ticket to request support for an additional format.

Localize all strings that are presented to the user: buttons, labels, dialog boxes, etc. Exceptions are the detailed error messages you may receive from a server. Don't translate server messages on the integration side by matching the text.

Log messages are written in English and not translated.

Check all translatable strings and log messages using Acrolinx to avoid delivering builds that contains spelling issues. Run an Acrolinx check on them.

Language Selection

The UI language set in the host editor determines which UI language is displayed in the Acrolinx Integration.

Fallback

If a translation for the relevant language is present, the integration should find it automatically. The integration shouldn't make any assumptions about what languages are available. If there's no translation for the language, then the integration must fall back to English (en). If English isn't found, the integration should display the developer English source string (ask Acrolinx). If no string is found at all, then the integration should display the key.

The Transifex Configuration File

See Confluence for details on the structure of the .transifex configuration file. The file needs to be present in each repository containing localization files. However, please let the DevOps team write and commit this file to your repository (for example, open a Jira ticket). DevOps can ensure that the configuration is correct because they have access to our Transifex installation.

During development, you must enter new strings in the "developer English" string set. When development of all new strings is complete, the Acrolinx L10n team will first review and correct the strings. These strings will appear in the “English” string set, but will also be merged back into the “developer English” string set. The Acrolinx L10n team will then translate the strings into additional languages, which will appear in the other localization files. Never edit any other language strings besides developer English, as these edits will be overwritten by the automated hook.

Key-Name Conventions

Keys should follow the naming convention:

<INTEGRATION_NAME>.<MODULE>.<TYPE>.<CONTROL_NAME>

In some formats, like JSON, the key could be a hierarchical structure.

The TYPE indicates what kind of interface component the string is associated with, for example:

  • Button
  • Title
  • Menu item
  • Label
  • Message

An overview can be found in the String Guidelines.

This is important information for the translator, since different language is used for different components. For example, buttons are associated with actions, so typically verbs are used (like “check”). For some other components, typically a noun (like “name”) is used.

If you have to use the same string in two places, it might make sense to have different keys for it. For example, the buttons of a dialog with two buttons ok and cancel might be renamed by L10N to yes and no. A dialog with one button typically uses ok and yes would look a bit strange.

The module could be a dialog, page, class or so. After the module string, add the element where the string could be found. The element is typically similar to the text or name you would give the control.

    ITEM.INTEGRATIONNAME.MENU.ABOUT=&About Acrolinx
    INTEGRATIONNAME.OPTIONSDIALOG.LABEL.CHECK=Check
    INTEGRATIONNAME.BUTTON.CANCEL=Cancel
    INTEGRATIONNAME.OPTIONDIALOG.MSG.ERROR.NO_VALID_SERVER_CONFIGURED=No valid server address is configured.
    INTEGRATIONNAME.MSG.INFO.ABOUT=Acrolinx Version\: {0}\n Build\: {1}\nDate\: {2}

If you have to replace parts of the string with variable values, a placeholder like {0} … {5} … {n} should be used. Make sure that the application doesn't crash if the placeholder is missing. Don't use string concatenation to include variables like: "string1" + variable1 + "string2" + variable2. Using string concatenation prevents translators from reordering variables. Reordering variables is required in some languages.

Example

Source:

  • string1 {0} string2 {1}

Target Language might require:

  • translation_string1 {1} translation_string2 {0}

Ensure that a value that is inserted into the string can't crash the application. Make sure that they can't be used to create some kind of injection attack. It's important to distinguish the placeholders from each other by numbering them, because they might occur in a different order in some translations.

If a placeholder is standing in for a number, then take care to avoid grammatical issues such as 1 items found. You might need to define three separate strings, for example:

  1. INTEGRATIONNAME.MSG.INFO.WITHNUMBER_ZERO=No items found.
  2. INTEGRATIONNAME.MSG.INFO.WITHNUMBER_ONE=One item found.
  3. INTEGRATIONNAME.MSG.INFO.WITHNUMBER_N={0} items found.

Try to avoid the usage of HTML or other markup inside the value - there might be some exceptions where it makes sense. In these cases, suffix the key by adding “.HTML”.

Please Note

If your application doesn't understand escape sequences in property files (like \\, \:, \=, \n etc.), then mention this to the DevOps team. They'll avoid complications with our Transifex integration. Add a note to the readme.md as well.

See Also