Strings

To prepare your app for localization, you need to:

1. Extract strings and put them into string file(s). This ensures your strings are separated from your code and handled independently.
2. Format these strings properly. This will ensure the formatting does not break anything, enable your team and other contributors to collaborate productively, and ensure translations are displayed correctly.

String-Extraction Tips

Extract all strings

Put all your strings into string file(s) so your team can collaborate on the strings without touching the source code.

We recommend the following file formats to save your strings in:
iOS: .strings or .stringsdict
Android: .xml
Web: .json

Use tools when available

Using tools to extract strings and create string files is much faster than doing them manually.

List of tools

Encode all strings in Unicode

Save string files with UTF-8 encoding, which is the default charset for standard string files in most frameworks.

String-Formatting Tips

Here's a checklist to make sure your strings are formatted properly for use. Getting them right from the get-go can save a huge amount of time down the road. Here are time-tested best practices:

Format with arguments in the syntax of your choice

If an app platform doesn't provide a mature localization APIs, don't DIY, but look for a localization library to fulfil the aspects you need.

For web, we recommend the ICU Message syntax and FormatJS. Here's a quick guide. They are popular in web app development.

For mobile, we recommend to follow the official supported syntax. Check with the formatter APIs of the app platform in order to use the appropriate formatter.

Format strings in a human-friendly way

To facilitate collaborations among copywriters, translators, or other members involved, it's best to format strings in a way that's readable and understandable to them.

Avoid HTML tags

<p><?=translate('<strong>&lt;p&gt;This is a &lt;a href="/a/link/to/heaven"&gt;link&lt;/a&gt; and I am loving it&lt;/p&gt;</strong>&lt;/a&gt;')?></p>

<p><?=translate('<strong>This is a %{link} and I am loving it</strong>', array(    'link'    =&gt; '&lt;a href="/a/link/to/heaven"&gt;' + translate('<strong>link</strong>') + '&lt;/a&gt;'))?></p>

Label the variable-element placeholders (arguments)

<p><?=translate("%$1s, you have got %$2s and %$3s in %$4s.", …)?></p>

<p><?=translate("%{username}, you have got %{item_1} and %{item_2} in %{place}.", …)?></p>

Not all platforms allow you to use argument naming. For example, there is no argument naming in Objective C for iOS but both Ruby on Rails and Django allow such an option.

If your platform doesn’t support argument naming, you can use OneSky's placeholder validation.

Name string keys the language most used by your collaborators

Use only one language and use the one most used by your collaborators. English is the most common choice given its widespread familiarity among professional translators.

Have a key name similar to the value meaning

Use meaningful key names as identifiers of strings for better understanding.

Format strings in a machine-translation friendly way

Standardize string key naming convention

1. Enable the use of automated refactoring, automated analysis or find & replace tools with minimal room for errors.
2. Depending on the application coding style:

• CamelCase
• snake_case
• dot.notation

Format strings in an all-languages-friendly way

Always wrap full sentences

<p><?=translate("You have got")?><?=$Item?></p>

<p><?=translate("You have got %{Item}", array('Item' => $Item))?></p>

Why?

Different languages may have different word orders. Breaking a sentence into smaller parts can make it impossible to translate accurately.

For example:

• For Turkish, translators often need to know the basic context of the object in order to decide how to translate the verb.
• For Japanese, the object might be put in front of the verb: あなたは%{Item}を持っている。

Always keep leading and trailing spaces wrapped

<p><?=translate("Places checked in:")?> <?=$NumberOfPlaces?></p>

<p><?=translate("Places checked in: %{Number}", array('Number' => $NumberOfPlaces))?></p>

Why?

In English, a space is needed between words or after certain punctuations. But for some languages, a space is not needed or might even introduce errors.

For example:

• In Thai, space acts like a full-stop in English.
• In Chinese, there are no spaces between words or after punctuations, e.g. 去過的地方：%{Number}