Skip to content
Newer
Older
100644 122 lines (99 sloc) 5.31 KB
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
1 <html>
2 <head>
fd61583 @dustinrue updated help, disabled bluetooth
authored
3 <title>ControlPlane Localisation Guide</title>
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
4 </head>
5 <body>
fd61583 @dustinrue updated help, disabled bluetooth
authored
6 <h1>ControlPlane Localisation Guide</h1>
2be63fc @dsymonds Update some git-related details in Localisation Guide.
dsymonds authored
7 <h2>9 August 2007</h2>
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
8
fd61583 @dustinrue updated help, disabled bluetooth
authored
9 <p>This is a brief overview of some important points that ControlPlane
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
10 localisers should know. If you are a new localiser, or haven't read
11 this file for a while, please review it.
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
12 </p>
f99af91 @dsymonds Start writing up a L10n guide for localisers.
dsymonds authored
13
14
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
15 <h3>Overview</h3>
16 <p>The end result of your localisation work will be a directory called
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
17 <tt>XX.lproj/</tt>, where XX is the two-letter lowercase ISO 639-1 code for your
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
18 language. Googling for "ISO 639-1" will provide lists for you to check.
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
19 Some examples are English (en), German (de) and French (fr).</p>
ab71a18 @dsymonds Flesh out overview, and create structure for the remainder of the L10…
dsymonds authored
20
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
21 <p>If you're creating a regional dialect localisation, the directory
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
22 should be called <tt>XX_YY.lproj/</tt>, where YY is the two-letter uppercase
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
23 regional designator as specified by ISO 3166-1. For example, Brazilian
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
24 Portguese will be in a directory called <tt>pt_BR.lproj/</tt>. The rest of this
25 guide only uses <tt>XX.lproj/</tt>, and that should be understood to include
26 <tt>XX_YY.lproj</tt> too.</p>
ab71a18 @dsymonds Flesh out overview, and create structure for the remainder of the L10…
dsymonds authored
27
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
28 <p>There are two main parts that need to be localised: the Strings file,
29 and the Nibs. Both of these have sections below.</p>
ab71a18 @dsymonds Flesh out overview, and create structure for the remainder of the L10…
dsymonds authored
30
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
31 <p>This guide is aimed at localisers who are <em>not</em> using a specialised
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
32 tool such as iLocalize. Those using such tools should consult that
33 tool's manual, but should still read this guide since much of it still
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
34 applies.</p>
8e71261 @dsymonds Add note about localisers who use special tools (iLocalize, etc.).
dsymonds authored
35
ab71a18 @dsymonds Flesh out overview, and create structure for the remainder of the L10…
dsymonds authored
36
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
37 <h3>Sending Updates</h3>
38 <p>If you've created or updated a localisation, you'll need to send it to
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
39 me (David Symonds) for it to be included in the next version of
fd61583 @dustinrue updated help, disabled bluetooth
authored
40 ControlPlane. Your options, in decreasing order of my preference, are
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
41 below:</p>
42
43 <ol>
2be63fc @dsymonds Update some git-related details in Localisation Guide.
dsymonds authored
44 <li>Do your changes in your own git repository (cloned from my tree), use
45 <tt>git format-patch master</tt> to generate patch files, and email those to me.</li>
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
46 <li>Zip up your <tt>XX.lproj/</tt> directory, and email it to me.</li>
fd61583 @dustinrue updated help, disabled bluetooth
authored
47 <li>Zip up the whole customised ControlPlane.app bundle, and email it to me.
2be63fc @dsymonds Update some git-related details in Localisation Guide.
dsymonds authored
48 (This is apparently the default way that iLocalize operates)</li>
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
49 </ol>
50
51 <p>If you're comfortable with Git, option 1 is far superior to the others,
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
52 since the commit logs will reflect you as the author and preserve your
2be63fc @dsymonds Update some git-related details in Localisation Guide.
dsymonds authored
53 comments about your changes and the right timestamps. It also helps to
54 verify that I've correctly received and applied your changes.</p>
297da84 @dsymonds Write section about sending in updates to the L10n guide.
dsymonds authored
55
56
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
57 <h3>Strings File</h3>
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
58 <p>The strings file, called <tt>Localizable.strings</tt>, is a UTF-16 text file,
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
59 and must be kept in that format. That means that you'll need to edit it
60 in a program that supports UTF-16 properly. Xcode and TextEdit are two
61 examples that are known to work well.
6c222bd @dsymonds Flesh out L10n guide's Strings file section.
dsymonds authored
62
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
63 <p>Each English phrase that needs translating into your language will
64 appear in the strings file as follows:</p>
65 <pre>
6c222bd @dsymonds Flesh out L10n guide's Strings file section.
dsymonds authored
66 /* Growl message title */
67 "Changing Context" = "Changing Context";
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
68 </pre>
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
69 <p>The first line, inside the <tt>/*</tt> and <tt>*/</tt> bits are
70 programmer-provided comments to help you understand where the phrase is used.
71 You should not edit this.</p>
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
72 <p>The second line consists of two strings, each marked with double
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
73 quotes, and separated by an equals sign. The left-hand string is the
74 English phrase; don't change this. The right-hand string is the
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
75 localised phrase; you need to edit this.</p>
6c222bd @dsymonds Flesh out L10n guide's Strings file section.
dsymonds authored
76
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
77 <p>Make sure you keep your translation consistent with things such as
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
78 punctuation, spaces, parentheses, quotes, and so on. Double quote marks
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
79 <em>inside</em> a phrase should be escaped with a backslash. For example,
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
80 <tt>"Doing \"%@\" now."</tt>.</p>
6c222bd @dsymonds Flesh out L10n guide's Strings file section.
dsymonds authored
81
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
82 <p>If the English phrase has a "format specifier" (usually <tt>%@</tt> or
83 <tt>%d</tt>, etc.), that indicates a point where something else will be
84 inserted
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
85 programmatically. You need to keep that in your translation, but it can
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
86 be in any position inside the string, as appropriate.</p>
ab71a18 @dsymonds Flesh out overview, and create structure for the remainder of the L10…
dsymonds authored
87
88
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
89 <h3>Nibs</h3>
90 <p>Nibs are edited with Interface Builder, which comes with the Mac OS X
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
91 Developer Tools. These should have come on one of the DVDs that came
92 with your Mac; otherwise, you can download it from
93 http://developer.apple.com/tools/xcode/ (quite a large download,
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
94 though!).</p>
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
95
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
96 <p>All the nibs in <tt>en.lproj/</tt> need localisation, <em>except</em> for
97 <tt>AboutPanel.nib</tt>. I'd recommend just copying all the other nibs over to
98 your <tt>XX.lproj/</tt> directory, and open them from there.</p>
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
99
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
100 <p>Almost every visible text string in each nib needs localisation,
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
101 including window titles, control labels and menu texts. Some do not,
cdd14e2 @dsymonds Add more HTML markup.
dsymonds authored
102 and they are usually marked with asterisks, such as <tt>*Action*</tt>. These
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
103 will be set programmatically, with the correct string being pulled from
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
104 your Strings file, so don't change them.</p>
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
105
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
106 <p>After changing a text string, it will often be shorter or longer than
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
107 the English string. If it is a string used in a window or panel (i.e.
108 not a menu option, etc.), you will need to tweak the layout of the
109 other controls to compensate. A handy hotkey is Cmd-= (hold the Command
110 key, and hit the Equals key), which will resize the selected text label
111 or control to the (hopefully) correct size. You can then use the dashed
112 blue guidelines to line things up correctly. Don't be afraid of
113 resizing various things (controls, text fields, whole windows, etc.) to
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
114 make everything fit neatly.</p>
9b1bd4c @dsymonds Wrap L10n guide to 72 columns.
dsymonds authored
115
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
116 <p>Be careful not to change any of the controls' properties other than the
fd61583 @dustinrue updated help, disabled bluetooth
authored
117 text label and sizes. If you do, you might prevent parts of ControlPlane
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
118 from working properly!</p>
6c222bd @dsymonds Flesh out L10n guide's Strings file section.
dsymonds authored
119
e8e07fd @dsymonds Do initial conversion of L10n guide to HTML.
dsymonds authored
120 </body>
121 </html>
Something went wrong with that request. Please try again.