Localization

- Use plain language, simple sentence construction, and active voice.

- Spell out acronyms.

- Avoid words with double meanings.

- Use articles before nouns.

Check with localization if you aren't sure. For example, take these two options:

"make sure you've got the right address"

"make sure you've got the correct address"

We wondered if we needed to use "correct" instead of "right" because of the multiple meanings of "right." But, it turns out it's common enough that it's okay.

English words can more than double in length in other locales. To get an idea of how long a string could grow search the cak locale in Transvision.

Humor often doesn’t translate so handle this with care. If there is a need for more personality in copy, include a localization note explaining the rationale behind the original choice and possibly provide a simpler alternative (for example, in the 2021  onboarding experience, “It starts here" was an alternative to “Fire starts here”).

Avoid US American sports analogies like "home run", and celebration or seasonal events that only make sense in some parts of the world (e.g. "mother day", "return to school" all happen at wildly different times).

If you anticipate that copy will pose some challenges in localization (for example, a new term or using slang like "Got 'em!"), draft a localization note in your design or copy file. Finalize the draft with your localization partner before handing off final files to developers so that localizers have access to them and can add them to the source files.

Example of a localization note.

See guidelines for truncation and wrapping of individual components. These guidelines are in the process of being incorporated into our new design system so that when you are writing and designing a menu, for example, you know how the menu should behave when strings are long.

- Components should account for string growth. If a particular string is pushing the limits, rephrase the original text with consultation from localization.

- You can also allow locales to use a different term (example: “extension” instead of “add-on”). In general, it’s not a good solution to have locale-specific versions of a string because this can lead to a potential disconnect for some users, e.g. reading documentation or articles in English, describing a feature or menu, that then have a completely different translation in another language.

Consult with the localization team. You may need to restrict the string to En-locales (talk with the product manager about this), or rely on re-using strings already localized in other files. Reuse should be the last resort — and strings can only be reused exactly as-is (no changes in casing or punctuation), and in exactly the same context (title as a title, etc.)

The localization team strongly advises against including text in an image. Localizing the text is very complex, if not impossible, because it would require every localized build to include a custom image with the text. Creating such images manually doesn’t scale for a large number of locales, and using automation to generate them presents several challenges (font support, layout, QA). If you don’t create custom localized versions, the other option is to use English for all locales and that’s not a good experience.