Random developer's thoughts

Initial-import

Imagine your project has been in production for years, is very mature, and was translated to many languages. Now you are about to use the Platform, but don't want to translate everything again. The solution is simple - just upload all data and the Platform will load every translated text it could find inside your files. And these texts will be marked as 'translated', so no more work for your Translators.

How it works (exactly)

The Platform doesn't differentiate between first-import-ever and subsequent imports with new languages, sheets, keys, and texts. To the Platform, there is only one difference: either the key is new, or the key is not new (obviously...). So it doesn't matter whether you perform first-import-ever with all translated text or just import text translated using some exotic method (for example, you have Translator who works directly with data files and gives them to you after finishing work with every module).

New key (and its texts)

When the Platform finds a new key in the data files, it will import the:

  • Key's code
  • Base-language text associated with that key
  • Text associated with that key for each non-base language

Old key (and its associated text)

When the Platform finds the key which is already known, (was imported in the past), it will update the base-language text associated with that key (the key is old, so the Platform already have has the old base-language text for it).

That's it. Nothing else will happen. This simply means: all non base-language text associated with that key are ignored. Yes - IGNORED. So, if you think you need to provide translation for some text, you shouldn't - it's a waste of time. the Platform won't trust you. You're a Developer. You write software. Please leave translation stuff to the Translators!

Of course, you can still act as a Translator for new keys. But you shouldn't; this is only intended as a way to initially import text translated outside the Platform. Don't use it to perform everyday work.

Tricky case (return from the dead)

As a Developer, you are probably not aware of the fact that in the Platform, nothing is lost. If you import language, a sheet, or a key, and later decide to remove anything from the project, the Platform will hide it, but won't delete it completely. In a web application, there is a switch to show deleted objects (Developers can use the web interface too, but they can't edit anything). Texts belonging to deleted languages or keys are not editable in the web interface. They won't be downloaded during synchronization. But they are there, forever. This is to preserve history for all texts -- Developers can't cheat and clear history by performing an empty import (import with no data, deleting all keys) followed by normal one. In fact, there IS a way to forget (and forgive) all mistakes: delete the project. This operation destroys everything, but only Manager can do that.

When you create a key, import it to the Platform, delete it, and import again, the Platform will mark that key as 'deleted'. Later, if you create the same key again and import, the Platform will undelete it. All associated texts will be editable again.

Here is third synchronization case: The Undeleted key rules are the same as for new keys.And here is third synchronization case:

You are able to import text for non base-languages. This permits you to cheat and act as a Translator: at first, you perform an empty import - everything will be marked as deleted - then you import as usual. All keys will be undeleted and your translations will be imported.

You CAN do that, but don't. Things will get messed up. If the Translator changed some text which you concurrently changed as well, performing the above manipulation will result in importing your version as well as the current one (and it will be marked as translated, so Translator won't be notified of the need to check if it's correct). Use this method only in special cases, such as when you want to perform a pseudo initial-import. This may be needed if you want to abandon current project's translation state and switch to something else. This is really an odd situation; maybe your Manager should create another project?

Empty text

Each data format has specified rules for extracting the key's code and text from data files. If for some a language file code-text pair is missing (this must be non base-language, because base-language file defines which keys 'exist'), text for that language is taken from base-language.
Sometimes you may encounter a situation where the non base-language files contain keys associated with empty text (your old translation framework could work that way). The empty text was simply left off for the Translator to write - you don't want the Platform to import them and mark them as translated.

That is solved by treating empty text as non-existent in data files. As usual, if text for non base-language is not found, it is taken from the base-language.

Validation of formatting parameters

This currently works only with .properties format in a limited fashion: a parameter is of the form {param_name}. Yes, it is a name between fancy brackets. You cannot escape { or } characters; if you want to include them in text, you have to disable parameter validation.