Angular i18n Merge Files

Simplify the maintenance of the translation messages of an Angular application by splitting them into multiple files.
This tool supports all the translation file formats accepted by Angular (ARB, JSON, XLIFF 1.2, XLIFF 2.0, and XTB (XMB)) .

Without this tool

Angular expects all the translated messages for a specific language to be on a single file, which can result in a large file that can be difficult to maintain and that can promote merge conflicts.

messages.pt.json

{
  "locale": "pt",
  "translations": {
    "msg1": "Mensagem 1",
    "msg2": "Mensagem 2",
    "msg3": "Mensagem 3",
    "msg4": "Mensagem 4"
  }
}

With this tool

Angular i18n Merge Files generates the final translation file (like the JSON of the example above) by merging multiple partial translation files.

component-one.messages.pt.json

{
  "msg1": "Mensagem 1",
  "msg2": "Mensagem 2"
}

component-two.messages.pt.json

{
  "msg3": "Mensagem 3",
  "msg4": "Mensagem 4"
}

The name of files to be merged must have the suffix .messages.[language-code].[format-extension] and this tool will automatically merge them in the final translation file.

Partial translation file structure

To avoid duplicating header data on the multiple files, this tools expects a reduced version of the structure expected by Angular.

JSON

{
  "msg1": "Message 1"
}

Show other formats

ARB

The full ARB's schema for the meta (@) attributes is supported.

{
  "msg1": "Mensagem 1",
  "@msg1": {
    "x-locations": [
      {
        "file": "src\\app\\component-name.component.html",
        "start": {
          "line": "0",
          "column": "69"
        },
        "end": {
          "line": "0",
          "column": "93"
        }
      }
    ]
  }
}

XLIFF 1.2

The full XLIFF's schema for the body.trans-unit element is supported.

<?xml version="1.0" encoding="UTF-8" ?>
<body xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <trans-unit id="msg1" datatype="html">
        <source>Message 1</source>
        <target>Mensagem 1</target>
        <context-group purpose="location">
            <context context-type="sourcefile">src/app/component-name.component.html</context>
            <context context-type="linenumber">4</context>
        </context-group>
    </trans-unit>
</body>

XLIFF 2.0

The full XLIFF's schema for the file.unit element is supported.

<?xml version="1.0" encoding="UTF-8" ?>
<file id="ngi18n" xmlns="urn:oasis:names:tc:xliff:document:2.0">
    <unit id="msg1">
        <notes>
            <note category="location">src/app/component-name.component.html:1</note>
        </notes>
        <segment>
            <source>Message 1</source>
            <target>Mensagem 1</target>
        </segment>
    </unit>
</file>

XTB (XMB)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE translationbundle [
        <!ELEMENT translationbundle (translation)*>
        <!ATTLIST translationbundle lang CDATA #IMPLIED>

        <!ELEMENT translation (#PCDATA|ph)*>
        <!ATTLIST translation id CDATA #REQUIRED>
        <!ATTLIST translation desc CDATA #IMPLIED>
        <!ATTLIST translation meaning CDATA #IMPLIED>
        <!ATTLIST translation xml:space (default|preserve) "default">

        <!ELEMENT ph (#PCDATA|ex)*>
        <!ATTLIST ph name CDATA #REQUIRED>

        <!ELEMENT ex (#PCDATA)>
        ]>
<translationbundle>
    <translation id="msg1">
        Mensagem 1
    </translation>
</translationbundle>

The DOCTYPE can be omitted for simplicity at the cost of losing validation and auto-completion in the IDE.

Generating the merged file

Install the NPM package for this tool:

npm install --save-dev ng-i18n-merge-files

And run the following command, which will generate the merged files under src/locale/messages.[language-code].[format-extension]:

npx ng-i18n-merge-files -f [format]

Running it automatically

The merged files can be automatically generated by binding it to the NPM scripts that require them.

packages.json

{
  "scripts": {
    "i18n:merge-files": "npx ng-i18n-merge-files -f json",
    "build": "npm run i18n:merge-files && ng build",
    "start:pt": "npm run i18n:merge-files && ng serve --configuration development,pt"
  },
  ...
}

Options

> npx ng-i18n-merge-files -h

Options:
      --version                    Show version number                 [boolean]
  -i, --in                         Folder which will be searched recursively for translation files to be merged.
                                   [string] [default: "{current working dir}\src"]
  -o, --out                        Folder where the merged translation files will be saved to.
                                   [string] [default: "{current working dir}\src\locale"]
  -f, --format                     Format of the translation file.
                                   [required] [choices: "arb", "json", "xlf", "xlf2", "xtb"]
      --id-prefix, --ip            Adds a prefix to the translation identifier based on the translation filename (see
                                   --id-prefix-strategy)
                                   [boolean] [default: false]
      --id-prefix-strategy, --ips  Naming strategy applied to the translation filename to generate the identifier prefix
                                   [choices: "camel-case", "as-is", "dot-case"] [default: "camel-case"]
  -h, --help                       Show help
                                   [boolean]

Show options details

id-prefix

If set, a prefix will be added to the translation message id based on the translation filename.
The same two JSON files from the initial examples would be merged into:

{
  "locale": "pt",
  "translations": {
    "componentOne.msg1": "Mensagem 1",
    "componentOne.msg2": "Mensagem 2",
    "componentTwo.msg3": "Mensagem 3",
    "componentTwo.msg4": "Mensagem 4"
  }
}

To change the naming strategy of the prefix, see id-prefix-strategy.

id-prefix-strategy

The naming strategy that will be applied to the translation filename to generate the message id prefix.

Example for message id msg1 on file component-one.messages.pt.json:

Strategy	Message id
camel-case	`componentOne.msg1`
as-is	`component-one.msg2`
dot-case	`component.one.msg1`

.gitignore

Add the line corresponding to the format being used to avoid committing the generated merged files.

messages.*.arb
messages.*.json
messages.*.xlf
messages.*.xtb

Sample applications

See sample/README.md.

marcioggs/ng-i18n-merge-files