LOCALISATION.html

<html>
<head>
	<title>ControlPlane Localisation Guide</title>
</head>
<body>
<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>


<h3>Overview</h3>
<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 
applies.</p>


<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 
below:</p>

<ol>
<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 ControlPlane.app bundle, and email it to me.
(This is apparently the default way that iLocalize operates)</li>
</ol>

<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>
<pre>
	/* Growl message title */
	"Changing Context" = "Changing Context";
</pre>
<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
inserted 
programmatically. You need to keep that in your translation, but it can 
be in any position inside the string, as appropriate.</p>


<h3>Nibs</h3>
<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 
http://developer.apple.com/tools/xcode/ (quite a large download, 
though!).</p>

<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>

</body>
</html>