Ubuntu Wiki

How to write for internationalization (i18n) and localization (l10n)

TableOfContents(2)

Examples are universal

When writing, there are times that you need to use examples to explain a subject matter. Always make it a rule that examples should be universal - regardless of the written language, the example will be understood by any reader. To make your examples "universal," here are some tips that can help you:

• When using screen captures, be consistent in their look and feel. If there is no localized equivalent of the screen capture, chances are, your sample will be used.
• Make your subjects simple. For example, a name like "Joe" is likely to be more familiar to everyone instead of "Pyotr" or "Shigetaka".

• Consider the cultural differences between nations when making examples. See Cultural considerations, below, for guidelines.

Use of numerals and figures

The improper use of Numerals and figures can provide the most confusion when translated to another language. Numerals are very important when it comes to measurements and even simple figures like date and time can have big differences between countries.

When writing dates, remember that different cultures have different ways of describing it. Therefore, you may want to consider the following conventions in writing dates:

• Use the correct date convention for your audience.
• When writing days and months, do not abbreviate these words. This will prevent confusion when translation work has begun on the finished document.
• Consider adding a small note in the document about the date convention being used.

When there is a need to write the time, it is better to write it in a 24 hour format. You should inform your audience the timezone and naming convention being used.

Using correct Terminology

Terminology is an area of writing that can cause a lot of confusion among translators. The following guidelines may help you prepare a language-friendly document suitable for translation.

• Choose words with one or very few meanings.
• Use simple verb forms in writing. Most verbs in the simple form will likely have an equivalent in another language.
• Do not use terms that are jargon or slang.
• Whenever necessary, define all special and technical terms in a glossary section of your document.
• Choose words that are easy to pronounce. Not all readers of your piece are native english speakers.
• Limit difficult words to technical terms so as not to slow down your audience when reading.
• Expressions for time, place and relationship should be as simple as possible.
• Always make sure your spelling is correct! Use a spellchecker and a dictionary when in doubt.

Cultural considerations

When writing documentation, always keep in mind that your work might be translated to another language. Because of this, you have to consider cultural differences on a global scale. Names, places, events, and actions should be chosen as carefully as possible when they are to be used in your work so as to avoid misunderstanding between parties concerned. Consider the following guidelines when writing:

• Do not use names of places, events, and actions that are historically bound to certain countries and their cultures. Some people may find it offensive for various reasons. The same applies to the use of religious references as it may inject a clash of beliefs among readers of your work.
• Informal expressions must be avoided at all times and may only be used when absolutely necessary. The end product of a translated document filled with colloquial and vernacular languages and expressions would make no sense at all.
• Date and time is expressed differently in many countries. You may consider writing them in the ISO 8601 standard method and indicate the conventions used in your document so that the translator can easily adjust the text to be translated.

CategoryDocteam