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.

Available Localizations

• French, courtesy of Ronald Leroux
• Traditional Chinese, courtesy of Jack M. H. Lin.
• Danish, courtesy of Mogens Thyregod.
• Japanese, courtesy of Daisuke Okada, Hiroto Sawane.
• German, courtesy of Jens Hembach and Goetz Goerisch
• Italian, courtesy of Massimo Finizio and Davide Tartaglia
• Traditional Chinese, courtesy of JT Lee

Desired Localizations

We are especially interested in localizing Sandvox into these languages. Contact us if you are interested.

• Spanish [COMING SOON!]
• Portuguese

How to localize Sandvox

Tools and Preparation

At this time, Localization needs to happen from Tiger, not Leopard.

You will need:

• iLocalize
• Tiger's Developer tools (XCode 2.5) installed so you can use Interface Builder. You can find the Developer's Tool on the Tiger Install DVD. If you are running Leopard, you still need to installl the old Xcode 2.5 system — it can be installed in a separate directory on your system so that you can also keep Xcode 3.0 around.
• Some experience using the Terminal application (in Utilities folder)
• These palette files installed in ~/Developer/Palettes folder (create the folders as needed):
  • RBSplitView.palette (We can send you an Intel-compatible version of this file)
  • PDFKit.palette copied from your <diskName>/Developer/Extras/Palettes folder
  • QTKit.palette copied from your <diskName>/Developer/Extras/Palettes folder

Interface Builder Setup

From the Preferences window in Interface Builder, choose "Lock All Connections".

Also, verify that the two extra palettes are installed:

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 nibs and strings, with a few exceptions, listed below.
• Look out for cases where there is a prompt to contact Karelia software. Please indicate that correspondence should be in English if possible.
• If you are not sure how to deal with spacing issues, where the translated text is significantly smaller than the English, take a look at how the French nib's layout handles the situation.

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).
• 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.

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

• Apple Style Guide version 2006
• Localization QuickStart
• Quick Tips of Interface Builder
• Apple Human Interface Guidelines

Feel free to check with Karelia if any terms 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.
• There are places where we should specify that something is in English....
  • Feedback.nib (the prompt of "Send a message to Karelia Software" can be replaced with a translation of "Please send your message in English if possible")
  • Screencast.nib: please indicate that the Sandvox screencast is in English, e.g. "Watch this screencast introduction to Sandvox (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.

Cleaning up the Nibs

Because languages vary greatly in their length, often more characters than English, it is necessary to check out all the nibs and make sure that the text fits, and make adjustments as necessary. There is a bit of an art to this. Please see the chapters on Controls and Layout Examples in the Human Interface Guidelines book referenced above for the proper sizing if you experience difficulties. Interface Builder should display the proper guides after activating them. Languages that are read from right to left are also a bit different.

If an entire nib window or view needs to be resized, hold down the control key while stretching a nib, to force the items inside to grow proportionally. Also hold down the shift key at the same time to constrain movement in one direction (generally, making the nib wider but not taller).

Inspector Nibs

The inspector plugin nibs are the trickiest, so they have their own section.

Enlarge (horizontally only please) whatever inspector nibs need to be widened, only as much as needed. From Interface Builder, hold down the control key while you stretch, so that the stretchable elements will expand properly. The margin should be 10 pixels on the right side, and continue to be 10 pixels at the bottom.

Once you have determined what this maximum width will be, be certain that none of the views in Info.nib and any of the plug-in inspectors get wider than this as you localize.

Determine the maximum width that you need for the widest element. This will be the new inspector width. You then need to update the following items:

• Info.nib: Change width of DetachedInfo window, and then the width of the KTStackView within that window
• Info.nib: Adjust SEGMENTS as described here:

SEGMENTS in Info.nib are the trickiest to adjust. The enclosing view should stay at the original height (16 pixels) but be expanded to the new inspector width. Set the NSSegmentedControl to have a top/left value of x=-8, y=-2. The problem with this is that you can't just stretch the view. We want the width to be inspector width + 8 on the left + 8 on the right, but the only way to do that it so change the width per segment from the Attributes tab (command-1) of the Interface Builder inspector. Try a value of (total width + 8) / 3 ... this seems to work.

Host Setup Nib

HostSetup.nib requires a bit of extra work because it is so complicated, with a tab view that handles all of the steps of this setup assistant. You can't just take a quick look at the nib file to see if all of the strings are properly spaced. You need to look at each step.

To select and view each step, first select the window from the nib window:

Then switch to list view using the list view icon in the upper left corner of that window. Keep disclosing the triangles until you open up the "KTBackgroundTabViewItem."
Double-click on each of these NSTabViewItem lines to select and display each step.

Delivering Localizations to Karelia

1. Use "Export Localization" from the "Project" menu.

2. If the export file created is not a ".zip" file, please create an compressed archive using the Finder.

3. Send the file it has created to Karelia.

How can we improve this page? Let us know.