If you're completely new to localization under Haiku, please read the very basic blog Localizing an application. Also see the Haiku Book and maybe search for examples in Haiku the tree with OpenGrok.

Quick links to the sections in this document:

Go up Overview

The whole localization business hinges around the en.catkeys that are collected from a project's source files.

Polyglot manages the strings of a project's en.catkeys in a database. Translated strings get added as a field to the English original as they arrive from the web interface.

Catkeys have no concept of the history of a particular string, so there is no "update" when a string in the en.catkeys changes:
When an en.catkeys file is uploaded, the unchanged strings are kept in the database (along with their translations) and all new strings are added (with no translations yet, of course).
Strings that aren't in the new en.catkeys anymore get removed (together with all their attached translations: just fixing a typo is then very costly, because the whole string has to be re-translated!).

Notable exception: If the English original only has whitespace or capitalization changes, Polyglot won't drop the whole string, but update the English original and keep the translation and marks it as Needs work.

When all the languages you need are 100% finished, you can export and download their xx.catkeys to use when building your application.

Non-catkeys translations

Polyglot can be used for the translation of other files than Haiku catkeys:

Go up Adding a project

Simply enter the new project name into the Add project text box on the Polyglot start page, click Add and it'll appear in the list of projects. Click on it and you get to the Translation modules page of your project:

The "Translation modules" page to name parts of your application that need translation.

Here you enter the name of the translation module you want to add. If it's for the main part of your app it should be called simply "Application". Then you choose the kind of file (Haiku catkeys, line-separated, or Java properties) from the pop-up menu and click on "Add".

You arrive at a page to upload the English original for the added module (here for a catkeys module):

Uploading the en.catkeys

After you've uploaded a file, you'll see for all kinds of files:

The properties of en.catkeys

Additionally for Haiku catkeys:

Additionally for line-separated files:

The properties of a line-separated file

Under all that follows the contents of your uploaded file.

If your project only uses a single en.catkeys file that contains all the strings, you're done now. If you use several en.catkeys to build your software, maybe for a "Preferences panel", a "Tracker add-on", and a "Library", you need several "Translation modules" and need to repeat these steps and add the appropriate identifying names and upload their en.catkeys (or line-separated files, or Java properties).

Go up Uploading existing, already translated files

If you already have some (partially) translated xx.catkeys (or line-separated files, or Java properties), you can upload those too: Just like your translating collegues, you click on your project on the start page, and then on the Continue or All text blocks link of each language you have already translated files for.

The "Translation" page

At the top, you can now upload the translated file for that language.
When you read the info box, you see that you now have to deactivate the Needs work button and click Save for all strings that didn't need translation, because they are the same as the English original. Depending on the language, this is quite common e.g. for OK buttons or the name of the application.

Uploading translated files has no effect on English original. Changes always go from the original to the translations, never the other way around.
If the uploaded translated file is outdated and contains additional, now obsolete strings, those strings are simply discarded. Only strings that have the counterpart of their English original in Polyglot's database are imported.

Go up Updating the English original file

It's practically the same as when you created your new project.
You click on your project on the start page to get to your Translation modules page and then click on the Edit link of the identifying name (default "Application") and you're back where you can upload an English original file.

You can return to this page anytime you need to upload a new version of your English original file. Remember from the "Overview" section though: uploading a new original file will lose already translated strings, if their English original string has changed. Don't wear out your translators...!

Go up Exporting translated files

On the Translation modules page, each language has an Export item in the Continue menu beside its progress bar. With it you download the translated file of that particular language. To download a ZIP archive containing all languages (with the folder hierarchy defined in the "Path" text field), click on the Export all at the bottom of the list of languages on that page.

Go up Tips

Go up TL;DR (catkeys)

Getting a catkeys project going, in a nutshell:

  1. Read at least the "Overview" on this page. :)
  2. Add a new project.
  3. Add "Translation modules" for the different parts of your app that create en.catkeys (often just one en.catkeys file is used, default name "Application").
  4. Upload the en.catkeys.
  5. Add all existing translated xx.catkeys on the Translation modules page of each language you got. Un-set the Needs work checkbox and click Save for those strings that didn't need translation, because they are the same as the English original, e.g. often for OK buttons.
  6. Uploading a new en.catkeys file impacts the translations (items get added or removed, including already translated strings!). Uploading translations (xx.catkeys) doesn't impact the en.catkeys.
  7. Export the translated xx.catkeys for the languages that you need when their translations are finished.