1
<chapter id="styleguide-international">
2
<title>Writing for an International Audience</title>
3
<para>How to write for internationalization (i18n) and localization (l10n) </para>
4
<sect1 id="international-1" status="help">
5
<title>Examples are universal</title>
6
<para>When writing, there are times that you need to use examples to explain a
7
subject matter. Always make it a rule that examples should be universal -
8
regardless of the written language, the example will be understood by any reader. To
9
make your examples "universal," here are some tips that can help you:</para>
12
<para>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.</para>
15
<para>Make your subjects simple. For example, a name like "Joe" is likely to be more familiar to everyone instead of "Pyotr" or "Shigetaka".</para>
18
<para>Consider the cultural differences between nations when making examples. Refer to <xref linkend="international-4" /> for guidelines.
23
<sect1 id="international-2" status="draft">
24
<title>Use of numerals and figures</title>
25
<para>The improper use of Numerals and figures can provide the most confusion when
26
translated to another language. Numerals are very important when it comes to
27
measurements and even simple figures like date and time can have big differences between
29
<!-- Date Convention section -->
30
<para>When writing dates, remember that different cultures have different ways of describing
31
it. Therefore, you may want to consider the following conventions in writing dates:</para>
34
<para>Use the correct date convention for your audience.</para>
37
<para>When writing days and months, do not abbreviate these words. This will prevent
38
confusion when translation work has begun on the finished document.</para>
41
<para>Consider adding a small note in the document about the date convention being
45
<!-- Time Convention section -->
46
<para>When there is a need to write the time, it is better to write it in a
47
24 hour format. You should inform your audience the timezone and naming convention being
50
<sect1 id="international-3" status="draft">
51
<title>Using correct Terminology </title>
52
<para>Terminology is an area of writing that can cause a lot of confusion among translators. The following guidelines may help
53
you prepare a language-friendly document suitable for translation.</para>
56
<para>Choose words with one or very few meanings.</para>
59
<para>Use simple verb forms in writing. Most verbs in the simple form will likely
60
have an equivalent in another language.</para>
63
<para>Do not use terms that are jargon or slang.</para>
66
<para>Whenever necessary, define all special and technical terms in a glossary
67
section of your document.</para>
70
<para>Choose words that are easy to pronounce. Not all readers of your piece are
71
native english speakers.</para>
74
<para>Limit difficult words to technical terms so as not to slow down your audience
78
<para>Expressions for time, place and relationship should be as simple as
82
<para>Always make sure your spelling is correct! Use a spellchecker and a dictionary
87
<sect1 id="international-4" status="draft">
88
<title>Cultural considerations</title>
89
<para>When writing documentation, always keep in mind that your work might be translated to
90
another language. Because of this, you have to consider cultural differences on a global
91
scale. Names, places, events, and actions should be chosen as carefully as possible when
92
they are to be used in your work so as to avoid misunderstanding between parties
93
concerned. Consider the following guidelines when writing:</para>
96
<para>Do not use names of places, events, and actions that are historically bound to
97
certain countries and their cultures. Some people may find it offensive for
98
various reasons. The same applies to the use of religious references as it may
99
inject a clash of beliefs among readers of your work.</para>
102
<para>Informal expressions must be avoided at all times and may only be used when
103
absolutely necessary. The end product of a translated document filled with
104
colloquial and vernacular languages and expressions would make no sense at
108
<para>Date and time is expressed differently in many countries. You may consider
109
writing them in the ISO 8601 standard method and indicate the conventions used
110
in your document so that the translator can easily adjust the text to be
added
removed
generic/styleguide/international.xml
