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.

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 their catkeys translated

After adding the translation module for this main part of your app (by default named "Application"), you upload the en.catkeys for it:

Uploading the en.catkeys

Below that you'll see the name of the translation module, the signature of the application and the checksum which changes every time you create a new en.catkeys with changed GUI strings:

The data of a translation module

Under that follows the contents of your en.catkeys.

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-addon, 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.

Go up Uploading existing xx.catkeys (translations)

If you already have some (partially) translated xx.catkeys, 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 xx.catkeys for.

The "Translation" page

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

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

Go up Updating en.catkeys

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 en.catkeys file.

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

Go up Exporting translated xx.catkeys

On the Translation modules page, each language has an Export item in the Continue menu beside its progress bar. With it you download the xx.catkeys of that particular language. To download a ZIP archive containing all languages, click on the Export all at the bottom of the list of languages on that page.

Go up Tips

Go up TL;DR

Getting a 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 original English, 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.