The translation builder is a part of AppDoc. You can find it under ControlPanel > Tools > AppDoc and then clicking either "Global Translation" to access the global website translation files, or select a specific app and click "Languages" on that screen.

Permissions

To work on a translation you will likely need to adjust the server's folder permissions in two places:

1) The inc/lang folder. To do this, use the following Unix command (or use an FTP client that can adjust permissions if you don't have shell access to the server):

chmod -R 777 inc/lang

2) In any specific app there needs to be a 'lang' folder which is writeable by the web server. If the folder doesn't exist, then AppDoc will try to create it for you in which case the app folder itself will have to be writeable. To make all app folders writeable (but not the files inside them, which don't need to be) use the following command:

chmod 777 inc/app/*

If the language folder exists and AppDoc complains it can't write to it, then you'll need to execute the following command for the specific app in question (change APPNAME to the real app's name for the command to work):

chmod -R 777 inc/app/APPNAME/lang

Once you have the permissions set (should be a one-time thing), you should now be able to begin using the translation builder features.

Usage

The interface to the translation builder starts with a list of languages. Each language has certain properties (code, locale, character set) and can be selected to edit its properties and to edit the text for that translation as well in a wizard-like manner. New languages can be added with the "Add Language" link.

When you first begin translating a new app or when you make changes to your global templates, you will need to click the "Build index" or "Re-build index" button on the top right corner of the list of languages. This goes through the selected app and finds any text strings that are marked to be translated. It parses .spt templates for {intl Some text} tags, global XT templates for <xt:intl>Some text</xt:intl> tags, as well as PHP files for calls to intl_get ('Some text') and then saves these to an list which can be used to build translations into new languages.

Defaults and Fallbacks

One language should be the default. Others can also specify fallback languages as intermediate options before choosing the default for a given piece of text. This list of languages is compared to a visitor's browser settings to automatically negotiate the best language for that user based on their preferences and what's available.

So for example, you may have a main French translation and then another regional French Canadian language. The French Canadian would cite the regular French as a fallback, and would then translate only the strings that are spoken differently in Canadian French than in traditional French.

Then if a visitor came from France and had their browser settings set to prefer French when available, Sitellite would automatically show them the French version of the site. Where a French translation isn't available for a specific piece of text (should the translation not be complete, for example), the default language (say, English) would be shown for that text.

If a French speaking Canadian came to the site with Canadian French in his browser preferences, the site would see this and show him the text from that translation. Where that translation is incomplete, the traditional French would be shown instead, and where that is not available either, it would default to the default language.

This allows for some localization of websites in addition to simply translating them. Regional differences within the same language are often substantial and can impact the intended meaning of your website content, so this level of flexibility is important in order to be able to deliver your content accurately throughout the world.