i18npack
Keeps multiple i18n files in a single YAML file.
Most tools that work with i18n data expect translations to be separated by language. i18npack allows you to keep translations for all languages in the same file so you can glance at all translations without switching to another file. It's based on js-yaml and thus only supports YAML files as source.
Installation
npm install i18npack
Usage
var i18npack = ; // Use a glob pattern to specify filesi18npack; // ...or pass an array of file names. options is optional.i18npack; // Set default options if you don't want to pass it each time.i18npacksettingslanguages = 'en' 'fr'; // ...and you can reset options later if necessary.i18npack;
i18npack supports glob patterns. See glob documentation.
Examples
Given these two source files and option { languages: ['en', 'fr'] }
,
bio.yaml
name: "John Smith"job: !t - "engineer" - "ingénieur"
pages.yaml
index: pageTitle: !t - "My Website" - "Mon site web" url: "http://www.mywebsite.com"
they are transformed into:
en.json
fr.json
Note that the __lang__
and __langs__
are added automatically, but if these placeholders are already taken, then they are not overwritten. Also, you can choose to not include them by default by setting includeLangDetails
in the options to false.
Language Keys
If there are many languages, it may be convenient to prefix each translation by a language code. These codes need to be the same ones specified in options
. Also, the order is not important, but it is not possible to key only some translations.
greetingText: !t - en: Welcome! - fr: Bienvenue! - da: Velkommen! - ja: ようこそ!
i18npack YAML Types
i18npack uses several built-in cusyom YAML types to help you organize strings better.
!t
Takes a list of scalars and selects one that corresponds to the current language being generated. The order of the items in the list determine the language, and it corresponds to the order defined in the languages
option.
See examples above.
!struct
Takes a specified JSON schema and validates a block against the Draft v7 schema using ajv. To specifiy a schema, use _schema
in the source and specify the name of the file containing it. Use jsonValidatorOptions
to pass options to the validator (See their documentation for available options). If you are unfamilier with JSON schema Draft v7, try using http://jsonschema.net to generate it.
book.yaml
book: !struct _schema: book.json title: Alice's Adventures in Wonderland auothor: Lewis Carroll
book.json
!extend
Reads a YAML file and _.extends the current block with the file content.
book: !extend _base: book.yaml published: 1865
Result:
Custom YAML Types
You can also specify your own YAML types. See js-yaml documentation for more details.
var options = customTypes: { return 'Hello, ' + value + '!'; } { return Mathmax; } ; i18npack;
test.yaml
msg: !greet John SmithmaxValue: !max - 10 - 5 - 21 - 5foo: !!str 123bar: 123
Result:
Using Templates
It is possible to reference a value from any source files so you don't need to repeat the same values in many places. JSON Query is supported in i18npack to make this possible. To use it, enclose the query in the {{ }}
delimiter, and
wrap it inside double quotes:
bio.yaml
name: "John Smith",homepage: "{{ pages.index.url }}"
pages.yaml
index: url: "http://www.mywebsite.com"
Result:
bio: name: "John Smith" homepage: "http://www.mywebsite.com"pages: index: url: "http://www.mywebsite.com"
Handling Empty Strings
By default, empty strings are not included in the output. To change this behavior, use the allowEmptyTranslations
option.
Options
You can override the default options as follows so you don't need to pass the option object each time. If you need to reset changes, use i18npack.reset()
.
i18npacksettingsdest = 'data/translations';
languages
Type: array
Default: ['en']
An array of supported languages.
dest
Type: string
Default: '.'
The path of a destination directory.
schemaDir
Type: string
Default: '.'
The directory containing schemas for source files.
includeLangDetails
Type: boolean
Default: true
If true, the __lang__
and __langs__
properties will be added to the output files.
jsonValidatorOptions
Type: object
Default: {}
The options passed to the JSON validator.
delimiter
Type: RegExp
object
Default: /{{([\s\S]+?)}}/g
The delimiter used for processing templates. It must have one regex group and the global flag g
.
customTypes
Type: object
Default: {}
An object of key-value pairs containing custom YAML types. See js-yaml documentation for more details.
strict
Type: boolean
Default: false
If true, an error is thrown if the number of provided translations is less than the number of the supported languages.
allowEmptyTranslations
Type: boolean
Default: false
If true, empty translations are included in the output.
ext
Type: string
Default: '.json'
The file extension of output files.
mergeFilesAtRoot
Type: boolean
Default: false
If true, the output of each file will be merged at the root. Otherwise, each file is namespaced by its file name. Note that if there are keys with the same name coming from multiple files, an error will be thrown.