ilib-loctool-yaml

Ilib loctool plugin to parse and localize YAML files.

Configuration

By default, plugin will localize source .yml and .yaml files, e.g. /project/en.yml, and write localized file to a subfolder: /project/resources/ru-RU/en.yml.

The plugin will look for the yaml property within the settings of your project.json file. The following settings are used within the yaml property:

• mappings: a mapping between file matchers and an object that gives info used to localize the files that match it. This allows different yaml files within the project to be processed with different schema. The matchers are a micromatch-style string, similar to the the includes and excludes section of a project.json file. The value of that mapping is an object that can contain the following properties:
  • template: a path template to use to generate the path to the translated output files. The template replaces strings in square brackets with special values, and keeps any characters intact that are not in square brackets. The default template, if not specified is "resources/[localeDir]/[filename]". The plugin recognizes and replaces the following strings in template strings:
    • [dir] the original directory where the matched source file came from. This is given as a directory that is relative to the root of the project. eg. "foo/bar/strings.yaml" -> "foo/bar"
    • [filename] the file name of the matching file. eg. "foo/bar/strings.yaml" -> "strings.yaml"
    • [basename] the basename of the matching file without any extension eg. "foo/bar/strings.yaml" -> "strings"
    • [extension] the extension part of the file name of the source file. etc. "foo/bar/strings.yaml" -> "yaml"
    • [locale] the full BCP-47 locale specification for the target locale eg. "zh-Hans-CN" -> "zh-Hans-CN"
    • [language] the language portion of the full locale eg. "zh-Hans-CN" -> "zh"
    • [script] the script portion of the full locale eg. "zh-Hans-CN" -> "Hans"
    • [region] the region portion of the full locale eg. "zh-Hans-CN" -> "CN"
    • [localeDir] the full locale where each portion of the locale is a directory in this order: [langage], [script], [region]. eg, "zh-Hans-CN" -> "zh/Hans/CN", but "en" -> "en".
    • [localeUnder] the full BCP-47 locale specification, but using underscores to separate the locale parts instead of dashes. eg. "zh-Hans-CN" -> "zh_Hans_CN"
  • excludedKeys - an array of keys that must be excluded from a ResultSet. Excluded key will also affect all its children and ignore them too. It only allows the direct key exclusion, i.e. a sequence of keys can not be used.
  • commentPrefix - a string that defines prefix for context comment for translators. Only comments that start with the provided string will be extracted and added to ResultSet, all other are ignored.
• checkTranslatability: by default, the plugin tries to guess which values in the file are strings for translation and filter out others; setting checkTranslatablility: false will disable this behaviour and all values from the file will be extracted.

Example configuration:

{
  "settings": {
    "yaml": {
      "mappings": {
        "**/source.yml": {
          "template": "resources/[localeDir]/source.yaml"
        },
        "src/**/strings.yaml": {
          "template": "[dir]/strings.[locale].yaml",
          "excludedKeys": [
            "one",
            "another",
            "test"
          ],
          "commentPrefix": "L10N:"
        }
      }
    }
  }
}

In the above example, any file named souce.yml will be parsed. The output files are saved to the resources directory.

Also files named strings.yaml that are located in directory src or any of its subdirectories will be parsed using specified excludedKeys and commentPrefix rules.

Providing context comments

The plugin automatically parses yaml comments and assigns them to corresponding strings as context comments.

A context comment must be placed above the source string. It's also possible to use multiline comments.

Same line comments are ignored!

header_text: "Header" #ignored comment
# Comment for article_title.
article_title: "Article:"
# Comment for article_summary,
# it includes view count and edit count values.
article_summary: "Stats: {view_count} views, {edit_count} edits"

Comments are trimmed upon extraction, therefore there's no difference between these two comments.

#comment
first: "first"
#     comment <some extra space chars here>
second: "second"

Multiline comments will preserve line breaks as well as spaces on a new line (only space chars at the beginning of the first line and at the end of the last is trimmed):

#    Multiline comment
#    with some extra spaces in between <some extra space chars here>

would be parsed as Multiline comment\n    with some extra spaces in between

Legacy setup

Important: automatic schema files lookup is disabled once mappings section is specified in the project.json! Use configration parameters in a mapping as described above.

Prior mappings introduction that happened in v1.3.0 the plugin behavior was configurable via *-schema.json files.

For each source file plugin will search for a schema file named <sourceFileName>-schema.json in the same dirctory the source file is located.

Schema file

Example of *-schema.json file:

{
  "useLocalizedDirectories": false,
  
  "excluded_keys": [
    "testKey",
    "anotherExcludedKey"
  ],
  
  "outputFilenameMapping": {
    "ru-RU": "/project/translations/ru.yml"
  }
}

useLocalizedDirectories - specifies whether localized file should be placed in a separate directory. Default: true

excluded_keys - array of keys to be excluded from localization (in v1.3.0 this key was changed to excludedKeys, nevertheless the original key with an underscore is still supported even in mappings)

outputFilenameMapping - array of mappings that specify output path for a locale: <localeName>: <path

License

This plugin is license under Apache2. See the LICENSE file for more details.

Release Notes

See CHANGELOG.md