UIZE JavaScript Framework

TO DO - Uize.Services.LocAdapter

This is a TO DO document for the Uize.Services.LocAdapter module.

1. Translation Metrics

Implement support for producing metrics reports for translated strings.

In particular, provide assessment of expansion factors for translated strings, by comparing the translated strings to their equivalent primary language versions.

what is the expansion factor?
expansion factor should be based upon translatable words (i.e. excluding tokens and word splitter segments)
separate expansion factors for words and characters

1.1. Layout Issue Prediction

Produce assessment of potential layout problems by comparing expansion factor for translated strings to pseudo-localization expansion factor.

For translated strings with an expansion factor greater than the pseudo-localization expansion factor, consider these candidates for layout checks. In particular, for such strings where the primary language string is relatively short or has few words, these are more likely to cause layout issues, since much larger strings are probably accommodated by flexible layout approaches. Furthermore, if all other translations of the string for other languages are shorter than the language being assessed in the report, this is a clue that the other language translation already needed to be adapted to fit within layout constraints. Besides using clues and heuristics to guide the analysis, explicit information about layout constraints for specific strings contained in meta data can be used.

2. Add Support for Plural Forms

2.1. Different Pluralization Formats

Qt Pluralization
Android Pluralization
gettext Pluralization

2.1.1. GNU gettext

EXAMPLE

msgid "I will call you back in one minute."
msgstr "I will call you back in one minute."

msgid_plural "I will call you back in <number:CN> minutes."
msgstr[0] ""
msgstr[1] ""
msgstr[2] ""

2.2. YAML

2.2.1. Sub-object With Special Name

EXAMPLE

newMessages
  [plurals]
    zero: You have no new messages.
    one: You have one new message.
    two You have two new messages.
    5: You have five new messages.
    other: You have {count} new messages.
    few: --
    many: --

2.2.2. Object With Special Key

EXAMPLE

newMessages
  [plurals]
  zero: You have no new messages.
  one: You have one new message.
  two You have two new messages.
  5: You have five new messages.
  other: You have {count} new messages.
  few: --
  many: --

2.2.3. String Key With Special Suffix

EXAMPLE

newMessages[plurals]
  zero: You have no new messages.
  one: You have one new message.
  two: You have two new messages.
  5: You have five new messages.
  other: You have {count} new messages.
  few: --
  many: --

2.3. Basic Use Case

In a basic use case, a reduced set of plural forms can be specified for a primary language (e.g. US English) resource file...

EXAMPLE

newMessages
  [plurals]
    zero: You have no new messages.
    one: You have one new message.
    other: You have {count} new messages.

2.4. Normalized Form

2.4.1. Possible Approaches

all plural forms in flat list, with some form of special key suffix
all plural forms grouped together in an object

2.4.2. Requirements of Normalized Form

2.4.2.1. - any special keys should not be treated as a resource string

should not be sent for translation
should not be serialized as resource strings into resource files
should not confuse or otherwise interfere with diffing processes
ultimately, all plural variations of a string should be handled by translators as discrete resource string translations

2.4.2.2. - there must be the same number of strings per language

for languages for which certain plural categories are not applicable, the strings for the plural categories should exist but can be autofilled with a special code (such as "--" or "n/a") so that they appear to have been already translated

2.4.2.3. - it must be clear to the localization automation process that it is dealing with a string that has plural forms

perhaps it is the responsibility of the parseResourceFile and serializeResourceFile methods to handle the conversion to and from the normalized form
it should be possible to transpose in both directions between the native representation for plural forms and the normalized form

JSON

{
  newMessages:{
    'plural=zero':'You have no new messages.',
    'plural=one':'You have one new message.',
    'plural=two':'You have two new messages.',
    'plural=5':'You have five new messages.',
    'plural=other':'You have {count} new messages.',
    'plural=few':'--',
    'plural=many':'--'
  }
}

2.5. Plural Forms and Translation Memory

Ideally, the actual string text for different plural variations is different, to avoid problems with translations being picked up from translation memory.

This could potentially be accomplished by supporting a qualifier in the token syntax...

EXAMPLE

{
  newMessages:{
    'plural=zero':'You have no new messages.',
    'plural=one':'You have one new message.',
    'plural=two':'You have two new messages.',
    'plural=5':'You have five new messages.',
    'plural=other':'You have {count:other} new messages.',
    'plural=few':'You have {count:few} new messages.',
    'plural=many':'You have {count:many} new messages.'
  }
}

3. Configuration of Language Support Per Brand

Implement support for brand-specific configuration of supported languages.

if there is no explicit configuration of supported languages per brand, then use the base configuration of supported languages
for brand-specific strings, they are only placed in a language-specific canonical .json file if the brand supports the language
it should be possible to handle this all in the export method. If brand-specific strings don't exist for a language in the canonical .json file, then they won't appear in the exported translation jobs. Also, there won't be brand-specific resource files generated in the project's codebase from the import method for languages that aren't supported for the brand.

4. Repair on Export

The export implementation should be updated to perform repair / synchronization for non-primary language files.

Export should gather resources for each of the supported languages, and then serialize the single resources file per language. Upon gathering the resources for the primary language, the export process should determine which resource strings have changed for the primary language. For resource strings that have changed, the equivalent for each of the languages should be removed or blanked out. For any resource strings that have been removed, the equivalent for each of the languages should be removed.

Once the resources have been updated for each language to reflect changes made in the resources for the primary language, the single resource file for each language can be serialized and written. By gathering the resources per language during the export process, this opens up the possibility of blanking out an individual resource string in the codebase if the translations is problematic, and this blanked out resource string will then appear as a new string that needs translation when a job is created for translation.

5. Export Translation Job

There needs to be a method for exporting a translation job that will submit just the resource strings that need translation.

Exporting a translation job would...

iterate through the supported languages
for each supported language, find all resource strings for which the value is blank but the value in the source language is not blank
create a data object that has all the untranslated strings, along with their source language version
serialize and write the data object

6. Import Translation Job

There needs to be a method for importing the translated strings from a translation job, once an exported translation job has been submitted to a translator and translated.

Importing a translatiob job would...

iterate through the supported languages
for each supported language, open the translation job file for the language
open the resouce strings file for the language
stitch the translated resource strings from the translation job file into the resource strings file
serialize the resource strings file and write it