Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
122 lines (99 sloc) 5.31 KB
<title>ControlPlane Localisation Guide</title>
<h1>ControlPlane Localisation Guide</h1>
<h2>9 August 2007</h2>
<p>This is a brief overview of some important points that ControlPlane
localisers should know. If you are a new localiser, or haven't read
this file for a while, please review it.
<p>The end result of your localisation work will be a directory called
<tt>XX.lproj/</tt>, where XX is the two-letter lowercase ISO 639-1 code for your
language. Googling for "ISO 639-1" will provide lists for you to check.
Some examples are English (en), German (de) and French (fr).</p>
<p>If you're creating a regional dialect localisation, the directory
should be called <tt>XX_YY.lproj/</tt>, where YY is the two-letter uppercase
regional designator as specified by ISO 3166-1. For example, Brazilian
Portguese will be in a directory called <tt>pt_BR.lproj/</tt>. The rest of this
guide only uses <tt>XX.lproj/</tt>, and that should be understood to include
<tt>XX_YY.lproj</tt> too.</p>
<p>There are two main parts that need to be localised: the Strings file,
and the Nibs. Both of these have sections below.</p>
<p>This guide is aimed at localisers who are <em>not</em> using a specialised
tool such as iLocalize. Those using such tools should consult that
tool's manual, but should still read this guide since much of it still
<h3>Sending Updates</h3>
<p>If you've created or updated a localisation, you'll need to send it to
me (David Symonds) for it to be included in the next version of
ControlPlane. Your options, in decreasing order of my preference, are
<li>Do your changes in your own git repository (cloned from my tree), use
<tt>git format-patch master</tt> to generate patch files, and email those to me.</li>
<li>Zip up your <tt>XX.lproj/</tt> directory, and email it to me.</li>
<li>Zip up the whole customised bundle, and email it to me.
(This is apparently the default way that iLocalize operates)</li>
<p>If you're comfortable with Git, option 1 is far superior to the others,
since the commit logs will reflect you as the author and preserve your
comments about your changes and the right timestamps. It also helps to
verify that I've correctly received and applied your changes.</p>
<h3>Strings File</h3>
<p>The strings file, called <tt>Localizable.strings</tt>, is a UTF-16 text file,
and must be kept in that format. That means that you'll need to edit it
in a program that supports UTF-16 properly. Xcode and TextEdit are two
examples that are known to work well.
<p>Each English phrase that needs translating into your language will
appear in the strings file as follows:</p>
/* Growl message title */
"Changing Context" = "Changing Context";
<p>The first line, inside the <tt>/*</tt> and <tt>*/</tt> bits are
programmer-provided comments to help you understand where the phrase is used.
You should not edit this.</p>
<p>The second line consists of two strings, each marked with double
quotes, and separated by an equals sign. The left-hand string is the
English phrase; don't change this. The right-hand string is the
localised phrase; you need to edit this.</p>
<p>Make sure you keep your translation consistent with things such as
punctuation, spaces, parentheses, quotes, and so on. Double quote marks
<em>inside</em> a phrase should be escaped with a backslash. For example,
<tt>"Doing \"%@\" now."</tt>.</p>
<p>If the English phrase has a "format specifier" (usually <tt>%@</tt> or
<tt>%d</tt>, etc.), that indicates a point where something else will be
programmatically. You need to keep that in your translation, but it can
be in any position inside the string, as appropriate.</p>
<p>Nibs are edited with Interface Builder, which comes with the Mac OS X
Developer Tools. These should have come on one of the DVDs that came
with your Mac; otherwise, you can download it from (quite a large download,
<p>All the nibs in <tt>en.lproj/</tt> need localisation, <em>except</em> for
<tt>AboutPanel.nib</tt>. I'd recommend just copying all the other nibs over to
your <tt>XX.lproj/</tt> directory, and open them from there.</p>
<p>Almost every visible text string in each nib needs localisation,
including window titles, control labels and menu texts. Some do not,
and they are usually marked with asterisks, such as <tt>*Action*</tt>. These
will be set programmatically, with the correct string being pulled from
your Strings file, so don't change them.</p>
<p>After changing a text string, it will often be shorter or longer than
the English string. If it is a string used in a window or panel (i.e.
not a menu option, etc.), you will need to tweak the layout of the
other controls to compensate. A handy hotkey is Cmd-= (hold the Command
key, and hit the Equals key), which will resize the selected text label
or control to the (hopefully) correct size. You can then use the dashed
blue guidelines to line things up correctly. Don't be afraid of
resizing various things (controls, text fields, whole windows, etc.) to
make everything fit neatly.</p>
<p>Be careful not to change any of the controls' properties other than the
text label and sizes. If you do, you might prevent parts of ControlPlane
from working properly!</p>
Something went wrong with that request. Please try again.