Localization

Sandvox Localization Agreement

Contact us first, before you start localizing! Please do not start localizing Sandvox without communicating with Karelia Software first as we may have agreed to let someone do a localization already. Non requested localization will not be accepted. Karelia Software will give priority to someone who has experience in localizing Mac OS X software.

Karelia Software reserves the right to edit or otherwise modify localizations, or to reject localizations if they do not meet Karelia's standards. Localizations submitted to Karelia may be incorporated by Karelia into Sandvox or otherwise used in any medium. All submitted localizations become the property of Karelia Software upon submission.

How to localize Sandvox

Tools and Preparation

You will need:

iLocalize
The latest beta version of Sandvox, ideally a version that we direct you to download. (Don't try to start with a release build.)
Developer tools (Xcode 3.x or 4.x) installed, as required by iLocalize
Some experience using the Terminal application (in Utilities folder)

General Techniques

The language name will be the ISO language or locale code. (Generally this is two lowercase letters.) Check with us if you are not sure what to use.
It's possible to get a "head start" on a language if it's one of Apple's major languages, because we can extract many of the standard strings from Apple's dictionaries. Look in the Help menu of iLocalize to connect to Apple's server to get the glossary files for your language. (Some of these files are more useful than others!)
Almost all localization can take place through iLocalize to edit the strings, with a few exceptions, listed below.
Be careful, and do not accidentally insert a newline at the end of a string. The only newlines that should be in the translations should also appear in the original.

Items not to localize

Do not localize the name Sandvox (unless it is customary in the target language to localize application names with made-up names).
special terms, in ALL CAPS, or surrounded by unusual punctuation like {total}, may need to be left alone. See the comments if possible. APPNAME should not be translated; it is replaced by Sandvox.
Also, occasionally you will find a note about localization (like "LOCALIZATION NOTE") in the text to translate. This is a note for you, not a string to be translated!
Terms like OtherViews, Item1, Item2, Item3, Small System Font Text, System Font Text do not need to be localized but copied over as-is, because they are placeholders, and never actually displayed to the user. Ninety-nine percent of the time, the terms Box and Panel. (as single words) do not need to be localized also, but simply copied over. The term Window should not be localized unless it is used in a menu item. Other strings that may not need localizing are digits/numbers, product names, trademarks.
Watch out for just the string "-". This is just a placeholder for text in the nib files, which is required to keep the font settings correct.

Terminology

Be sure to follow the terminology that Apple uses whenever possible.

If it is not entirely obvious, you may want to look at Apple's products or documentation to determine the matching term. For instance, the English "Photo Stream" is used in iPhoto, so you might want to use iPhoto and see what it is called in your language. (It may not be a literal translation!)

See Apple's Developer's site for these articles/documents :

Feel free to check with Karelia if any terms, or their context, are ambiguous, so we can explain and possibly improve the comments that accompany the words for future localization.

Special Cases

The store (from the "Buy/Register Sandvox..." menu), which is created by an HTML page served on Karelia's servers. Karelia will need to give you the list of words to translate for that.
It would be possible to translate other web pages of Karelia's but this is a lower priority.
A place where we should specify that something is in English....
- KSFeedback.strings: the prompt to send a message "Send a message to Karelia Software" should be treated as if it says "Send a message to Karelia Software, in English if possible" so that people will be encouraged to try to write to our support team in English.

Special Characters

The string "%@’s Site" contains a variable. A variable is something that will be replaced when the program runs. In French, for instance, the string needs to be localized as "Site de %@", so that the information in the string appears properly in the language. The following are also variables used to change the order that items appear in a sentence: %1$@, #%@.

The following strings are special characters which should not be changed either:
- \n = next line char
- \t = tab character.

Pay attention to the occasional string that starts or ends with a space. Please keep the space in the translation, since it is probably designed to be appended to another string, and losing the space would be strange.

Nib Warnings: We Are (mostly) Not Translating Nibs

We are using a technique in which the nib files are not directly localized. Instead, all of the strings in our nibs are found in .strings files. Therefore, you will get a lot of warnings about nibs nib being internationalized. The warnings will refer to files that are:

not located in language folder
compiled and cannot be localized

Ignore these warnings.

Nibs that we are translating

Note that we are translating "MainMenu.nib". This is the only exception. While you will see most nibs as empty (due to the above errors/warnings), MainMenu.nib will appear in your window as being translatable.

Delivering Localizations to Karelia

1. Choose Use "Export…" from the "Project" menu.

2. Choose the appropriate options to export only the language resources, and compress the result:

In iLocalize, click "Options" in the upper right corner. In the sheet that appears, we recommend checking both checkboxes in the "Output Name" section. In the "Output Format" section, please check "Only language folders" and "Zipped". In the final section of options, do not check "Compact nib files."

3. Send the file it has created to Karelia. You can email it, share a DropBox link, etc.