All localization service methods support the following set of common parameters...

1.2.1.1.1. project

node [pathToUize]build.js Uize.Build.Loc method=[methodName]
node [pathToUize]build.js Uize.Build.Loc method=[methodName] project=*

1.2.1.1.2. method

1.2.1.1.3. console

By default, the value for each non-translatable string is initialized to the corresponding value of the string from the primary language, but only if the non-translatable string is currently blank.

If this behavior is not suitable, one of the other available initialization modes can be specified using the initNonTranslatable parameter. The following initialization modes are supported...

An optional, comma-separated list of one or more of the project's translatable languages for which the export operation should be performed.

For more detailed information, consult the section Performing Methods for a Filtered Set of Languages.

An optional, comma-separated list of one or more of the project's translatable languages for which the import operation should be performed.

For more detailed information, consult the section Performing Methods for a Filtered Set of Languages.

The exportJobs method supports the ability to filter the strings that are exported to the translation job files, using the optional filter paramter.

SYNTAX

node [pathToUize]build.js Uize.Build.Loc method=exportJobs project=[projectName] filter=[filterName]

2.4.1.1.1. filterName

An optional, comma-separated list of one or more of the project's translatable languages for which the exportJobs operation should be performed.

For more detailed information, consult the section Performing Methods for a Filtered Set of Languages.

An optional, comma-separated list of one or more of the project's translatable languages for which the importJobs operation should be performed.

For more detailed information, consult the section Performing Methods for a Filtered Set of Languages.

An optional, comma-separated list of one or more of the project's translatable languages for which the auditTranslations operation should be performed.

For more detailed information, consult the section Performing Methods for a Filtered Set of Languages.

A locale code string, specifying the first of the two languages whose resource strings should be diffed.

The default value for this property, if not specified, is the locale code of the primary language configured for the project.

A locale code string, specifying the second of the two languages whose resource strings should be diffed.

The default value for this property, if not specified, is the locale code of the primary language configured for the project.

The service adapter can be configured for a project by specifying a module name for the serviceAdapter config option.

EXAMPLE

serviceAdapter:'MyNamespace.LocServiceAdapters.MobileAppAndroid'

Typically, each project has its own localization service adapter subclass, but it is possible for multiple projects to share the same service adapter module if they are all of the same type but differ in other aspects of their configuration.

The rootFolderPath config option lets you specify the path to the root folder under which all the project's codebase resource files can be found.

EXAMPLE

rootFolderPath:'~/git-repos/my-project/res'

If a relative path is specified for the rootFolderPath option, the path should be relative to the current directory at the time that the localization service scripts are run.

The languages config option lets you specify the translatable languages of the project, for which translation should be managed by the localization service.

It is recommended that the value specified for the languages option be an array of BCP 47 locale codes, containing both the language and region codes.

EXAMPLE

languages:[
  'de-DE',  // German
  'fr-FR',  // French
  'ja-JP',  // Japanese
  'nl-NL',  // Dutch
  'ru-RU',  // Russian
  'zh-CN'   // Chinese
]

The languages list may redundantly contain the primary language that is configured for the project in the separate primaryLanguage config option, but it is not required and it is recommended to omit the primary language from this list. In any event, the primary language is not considered to be a translatable language.

Lets you configure the translatable languages supported per brand.

It is not uncommon, in situations where a project supports multiple brands, for those brands to be associated with markets in different regions, with different regional languages for those regions. In projects that have brand-specific resource strings, the brandLanguages config option lets you configure different sets of translatable languages on a per brand basis.

EXAMPLE

brandLanguages:{
  fooBrand:[
    'de-DE',  // German
    'fr-FR',  // French
    'en-GB'   // English (Great Britain)
  ],
  barBrand:[
    'es-MX',  // Spanish (Mexico)
    'pt-BR'   // Portuguese (Brazil)
  ]
}

In the above example, the brand "fooBrand" supports three languages, while brand "barBrand" supports two languages. There is no overlap in the languages supported by these two brands. Resource strings that are specific to "fooBrand" are not translated to Spanish or Portuguese, while resource strings that are specific to "barBrand" are not translated to German, French, or British English. Resource strings that are not brand-specific and that are, therefore, common to these two brands will be translated for the superset of all the brand languages.

Lets you specify the primary language for the project.

The primary language is the language that will be used as the source of truth, and the resource strings from the primary language resource files will drive the translation process. Resource strings for the configured translatable languages of the project will be produced by translating the corresponding values of the strings from the primary language resource files.

EXAMPLE

primaryLanguage:'en-US'  // US English

It is fairly common for the primary language to be a regional variant of English (such as US English), but this is not a strict requirement. It is recommended that the value specified for the primaryLanguage option be a BCP 47 locale code, containing both the language and region codes.

Lets you specify the locale code to be used for the pseudo-locale.

It is recommended that the value specified for the pseudoLocale option be a BCP 47 locale code, containing both the language and region codes. It is further recommended that specifically the "en-ZZ" locale code be used for the pseudo-locale, since this locale code exists in a range of BCP 47 locale codes that are not assigned to specific languages and are free to be used for proprietary purposes such as pseudo-localization.

EXAMPLE

pseudoLocale:'en-ZZ'

Lets you specify configuration options for the pseudo-localization process that is performed when executing the export localization service method.

EXAMPLE

pseudoLocalization:{
  expansion:1.15,
  wrapper:'[]'
}

Generally, it is not necessary to explicitly configure the pseudo-localization process, since the default configuration should suit most projects. If any pseudo-localization option is to be configured differently for specific projects, it is likely to be the expansion factor. The most suitable expansion factor to use will be influenced by the set of translatable languages that the project needs to support, since different languages introduce different amounts of expansion during translation.

Lets you configure the whitespace options that should be used by the import localization service method when it writes codebase resource files.

EXAMPLE

resourceFileWhitespace:{
  indentChars:'    ',
  linebreakChars:'\n'
}

By default, resource files are serialized using a single tab character for indentation and a single new line character linebreaks. If these defaults are not suitable for the project's codebase, then the whitespace options can be specified explicitly using the resourceFileWhitespace config option.

3.1.2.8.1. Whitespace Options

The format of translation job files written by the exportJobs method can be configured using the translationJobFileFormat config option.

The translationJobFileFormat config option supports the following possible values...

For one thing, it is a waste of money to send non-translatable strings to translators.

Translators will likely not know what to do with such strings, and determining how to handle them may involve some costly back-and-forth communication between the project managers on both sides of the process. And if they actually translate such strings by accident, then they will charge for that translation work.

Accidental translation of strings that should not be translated can result in breakage of the application.

For example, a resource string may be used for storing a color value that should be different per language. Technologies such as CSS support named color values, such as "red" or "green". If the intention is to use the color red for one language and the color green for another language, it is not helpful if the actual text "red" is translated to some other language by the translators. Translating "red" to "rouge" in French would break the application in that the translated color value would not be recognized by CSS.

Instead, such a string should be treated as a non-translatable string, and it would then be the responsibility of a developer to manually change the value in the resource files of the translatable languages, under the direction of a product manager who makes the decision what colors best suit different language audiences.

Accidental pseudo-localization of some non-translatable strings (such as IDs or URLs) may break the pseudo-localized version of the application and hinder localization QA testing of the pseudo-localized version.

For example, if a resource string was being used to store a code like "AdvancedMode", where this code is being used by the application logic and is intended to be different per language, then pseudo-localizing the value from the primary language to "[ÅðṽåñçéðṀöðé__]" would break the application as it would not understand this value.

Implementing support for non-translatable strings in a project involves providing an implementation for the isTranslatableString instance method in the localization adapter subclass for the project.

The implementation in the adapter base class just returns true, so all resource strings are considered translatable by default.

An implementation for the isTranslatableString method should expect to receive a single argument, being a string info object that describes a resource string. The string info object will contain a key property that specifies the resource string's key name, along with a value property that specifies the value of the resource string for the primary language.

The method implementation should use the information in the string info object to determine a boolean return value, indicating whether or not the string is translatable. The implementation can use either or both of the key and value properties to reach its determination- whichever is best suited to the nature of the resource strings in the project.

EXAMPLE

function (stringInfo) {
  return (
    !/_(ID|EMAIL)$/.test (stringInfo.key) &&  // it's an ID or an e-mail address
    !/^https?:\/\//.test (stringInfo.value)   // it's a URL
  );
}

In the above example implementation for the isTranslatableString method, the method is first performing a test on the key of the resource string, checking to see if it ends with "_ID" or "_EMAIL". If this test fails, the method is then testing if the value of the resource string starts with "http://" or "https://".

While it is possible to write complex matching logic to test whether or not resource strings should be translatable, it is recommended that projects establish a simple and robust convention.

For example, a project could follow the convention that all non-translatable resource strings are indicated with a specific suffix or prefix in their key names. For instance, all non-translatable resource strings could have a "$" character appended to their key names.

EXAMPLE

function (stringInfo) {
  // string is translatable if its key doesn't end with "$"
  return stringInfo.key.slice (-1) != '$';
}

Following such a convention would provide the following benefits...

In order to verify that one's implementation of the isTranslatableString method for a project is doing the right thing, you can survey the strings that are determined to be non-translatable by using the metrics localization service method.

When you execute the metrics method, one of its by-products will be the strings info files that are written to the "strings-info" folder. The strings info is obtained from the resource strings in the primary language resource files for the project and is written to two different format files: one JSON format file, and one CSV format file.

Both of these two strings info files contain the same information, but expressed slightly differently. The CSV file is particularly easy to "consume" and can be loaded up in any spreadsheet editor (such as Google Sheets) that correctly supports the CSV format's ability to have quoted field values that contain line breaks (some of your resource strings may contain line break characters).

Once loaded into a spreadsheet tool, the Translatable column can be used to sort or filter the strings info rows based upon whether or not the strings are considered translatable. For non-translatable strings, the value in the Translatable column will be false. The spreadsheet can then be used to verify that there are no non-translatable strings being missed by the isTranslatableString method, and there are no translatable strings that are being incorrectly caught by it.

Non-translatable strings are never pseudo-localized when resource strings for the pseudo-locale are generated by the export localization service method.

Instead, the values from the primary language will be used as is.

Non-translatable strings are never exported to translation job files by the exportJobs localization service method.

This means that translators never have to deal with these strings, and there's never a possibility that translators will accidentally translate them, resulting in charges for wasted effort or even problems for the application.

Whenever a non-translatable string is added or modified for the primary language of a project, the values for the string for the translatable languages are initialized to the value from the primary language.

In this way, the values for the string in the resource files for the translatable languages don't need to be manually initialized by developers.

While the values for non-translatable strings are initialized to primary language values, the values for the strings in the translatable languages can subsequently be manually modified by developers.

Non-empty values for non-translatable strings in the resource files for the translatable languages of a project are respected throughout the localization automation process.

The total number of translatable words in all primary language resource files for the project is represented by the wordCount property.

The value of the wordCount property is only an estimate and the accuracy of the value depends on how well the project is defined to understand the difference between translatable words and non-translatable text.

The value of this property is useful when estimating the full translation cost for a project, since translators often charge for their services based upon word count and a cost per word.

The total character count for all the translatable words in all primary language resource files for the project is represented by the charCount property.

The accuracy of the value of this property depends on the accuracy of the wordCount property, since this property is the sum of the character count for all translatable words. This value can be useful when estimating the full translation cost for a project, since translators may base cost estimates for their services partially upon total character count for all translatable words.

The total number of resource files for the language is represented by the resourceFiles property.

The value of the resourceFiles property reflects the total number of codebase resource files for the language and not the total for all languages, so this value doesn't increase as you add support for new languages.

5.3.1.3.1. Brand-specific Resource Files

An identical translation is a translation where the value of a resource string in a translatable language is identical to the corresponding value of that resource string in the primary language.

Identical translations can be an indication of errors made during the translation process, where the source text is accidentally used unaltered as the translation. Information on all the resource strings that have identical translations for a given translatable language can be found in the identicalTranslations property in the translation audit report for the language. The value of the identicalTranslations property is an array of the form..

identicalTranslations:[
  identicalTranslation0OBJ,
  identicalTranslation1OBJ,
  ...
  identicalTranslationNOBJ
]

Each element of the identicalTranslations array is an object describing an instance of an identical translation, having the form...

{
  path:stringPathARRAY,
  value:stringValueSTR
}

The value of the path property is a string path array that contains all the information necessary to identify the resource string in the project, starting with the resource file that contains the string as the first element, and ending with the string key as the last element. The value of the value property is a string, specifying the value (i.e. text) of the string.

EXAMPLE

identicalTranslations:[
  {
    path:[
      'strings.xml',
      'OkButton'
    ],
    value:'OK'
  },
  {
    path:[
      'strings.xml',
      'FaxButton'
    ],
    value:'FAX'
  }
]

In the above example, two strings have translations that are identical to the source text from the primary language (English, in this case). This case can arise with a language like French, where it is acceptable to use "OK" and "FAX" in UI text. In fact, "OK" would even be considered preferable to using a stricter translation like "D'accord". So, in this case, the indentical translations are not an indication of a real problem.

An inconsistent translation is a case in which some source text contained in resource strings of the primary language is translated in more than one way in the resource strings of a translatable language.

Inappropriate inconsistent translations can arise in larger projects where translation jobs are distributed amongst multiple translators who translate in parallel and don't leverage shared translation memory, or when translation of future additions to an existing project are handed off to a new translation vendor without providing them with a translation memory or previous translations. Inconsistencies can also arise through basic mistakes in the translation process.

Information on all inconsistent translations for a given translatable language can be found in the inconsistentTranslations property in the translation audit report for the language. The value of the inconsistentTranslations property is an array of the form...

inconsistentTranslations:[
  inconsistentTranslation0OBJ,
  inconsistentTranslation1OBJ,
  ...
  inconsistentTranslationNOBJ
]

Each element of the inconsistentTranslations array is an object of the form...

{
  source:sourceTextSTR,
  translations:[
    translation0OBJ,
    translation1OBJ,
    ...
    translationNOBJ
  ]
}

The value of the source property is a string, specifying the source text from the primary language. The value of the translations property is an array of objects describing the different translations of the source text, where each object has the form...

{
  translation:translationTextSTR,
  strings:[
    stringPath0ARRAY,
    stringPath1ARRAY,
    ...
    stringPathNARRAY
  ]
}

The value of the translation property is a string, specifying the translated text from the translatable language. The value of the strings property is an array of string path arrays, identifying all the strings that have this translation for the translatable language. The value for each element of the strings array is a string path array that contains all the information necessary to identify the resource string in the project, starting with the resource file that contains the string as the first element, and ending with the string key as the last element.

The structure of the inconsistentTranslations object is illustrated by the following example, in which there are two different translations for the source text "Call".

EXAMPLE

inconsistentTranslations:[
  {
    source:'Call',
    translations:[
      {
        translation:'Appeler',
        strings:[
          [
            'strings.xml',
            'CallButton'
          ],
          [
            'strings.xml',
            'CallLink'
          ]
        ]
      },
      {
        translation:'Appel',
        strings:[
          [
            'strings.xml',
            'CallHistoryLabel'
          ]
        ]
      }
    ]
  }
]

In this example, the inconsistent French translations are legititate because the word "Call" is used as a verb in the first case (translated to "Appeler") and as a noun in the second (translated to "Appel").

The JSON format diff report is a serialized array of string diff objects, of the form...

[
  stringDiff0OBJ,
  stringDiff1OBJ,
  ...,
  stringDiffNOBJ
]

Each element of the string diff objects array is a string diff object of the form...

{
  key:keySTR,
  path:pathARRAY,
  valueInA:valueInASTR,
  valueInB:valueInBSTR,
  difference:differenceSTR  // 'different' | 'missing in A' | 'missing in B'
}

Each string diff object contains the following properties...

The structure of the JSON format language diff report is illustrated by the following example, in which there are two differences between the two languages compared in the diff...

EXAMPLE

[
  {
    key:'label',
    path:[
      'strings.js',
      'colorPicker',
      'label'
    ],
    valueInA:'color',
    valueInB:'colour',
    difference:'different'
  },
  {
    key:'tooltip',
    path:[
      'strings.js',
      'colorPicker',
      'tooltip'
    ],
    valueInA:'Click to choose a color.',
    valueInB:'',
    difference:'missing in B'
  }
]

The CSV format diff report is a table containing the following columns...

The structure of the CSV format language diff report is illustrated by the following example, in which there are two differences between the two languages compared in the diff...

CSV EXAMPLE

Resource File,Key,Path,Difference,Value in A,Value in B
strings.js,label,"['strings.js','colorPicker','label']",different,color,colour
strings.js,tooltip,"['strings.js','colorPicker','tooltip']",missing in B,Click to choose a color.,

The first portion of the initialization options specifies what resource strings should be initialized, and supports the following values...

The second portion of the initialization options specifies when (under which conditions) the strings should be initialized, and supports the following values...

The third portion of the initialization options specifies to what values the strings should be initialized, and supports the following values...

In a simple example, the value initialization feature can be used to initialize values of non-translatable strings.

To initialize the values of the non-translatable strings that are blank to the values from the primary language, one can use the following value for the initValues parameter...

initValues=non-translatable,blank,primary

In another example, the value initialization feature can be used to initialize all the strings for the en-GB (British English) language to the values from the primary language (presumably US English in this example), using the following parameters for the export method...

languages=en-GB initValues=all,always,primary

Note that we are using the languages parameter and specifying the value en-GB in order to perform this initialization during export for just the British English language (refer to the section Performing Methods for a Filtered Set of Languages).

Over the years, many resource string file formats have been standardized for different technologies.

Some examples of common resource file formats include...

In addition to the common (and somewhat standardized) resource file formats, projects can decide to use proprietary file formats.

Metrics report files are generated by executing the metrics localization service method.

Strings info files are generated by executing the metrics localization service method.

Translation audit report files are generated by executing the auditTranslations localization service method.

Language diff report files are generated by executing the diffLanguages localization service method.

Usage report files are generated by executing the usage localization service method.