diff --git a/docs/fundamentals/localization.md b/docs/fundamentals/localization.md index 36f5f34784..01bc471e69 100644 --- a/docs/fundamentals/localization.md +++ b/docs/fundamentals/localization.md @@ -264,3 +264,51 @@ Note that this hash key will only be appended to the translation based JSON file ### Translatable keys in Element + +### Extracting translatable keys + +An important part of the translation tooling is the extraction of translatable keys as a TypeScript +interface as well as the extraction of a JSON messages file with default translations. This is +provided by the `@siemens/element-translate-cli` package, which exposes the +`update-translatable-keys` command. Install it as a dev dependency: + +```sh +npm install --save-dev @siemens/element-translate-cli +``` + +The extraction happens on compiled files. I.e. make sure to run the build first. Then, to run these +extractions: + +```sh +npx update-translatable-keys +``` + +By default, this will pick up the configuration from a file `element-translate.conf.json`. To use a +different config file, pass it as the only argument to the command. + +The config file looks like this: + +```json +{ + "files": "dist/@siemens/**/fesm2022/**/*.mjs", + "configs": [ + { + "name": "element", + "locationPrefix": "projects/element-ng", + "keysFile": "projects/element-ng/translate/si-translatable-keys.interface.ts", + "keysInterfaceName": "SiTranslatableKeys", + "messagesFile": "dist/@siemens/element-ng/template-i18n.json" + } + ] +} +``` + +- `files` is a glob pattern for defining the files to scan. +- `configs` is an array of configs. For mono-repos building multiple libraries, they can be + separated into different configs. All keys are required: + - `name` is a unique name. + - `locationPrefix` defines the path prefix of the source files, important to distinguish between + different libraries in a mono-repo. + - `keysFile` defines the path of the generated TypeScript interfaces file. + - `keysInterfaceName` defines the name of the TypeScript `interface`. + - `messagesFile` defines the path of the generated messages JSON file. diff --git a/projects/element-translate-ng/README.md b/projects/element-translate-ng/README.md index 4640412656..634a3fd455 100644 --- a/projects/element-translate-ng/README.md +++ b/projects/element-translate-ng/README.md @@ -17,43 +17,11 @@ Install the library as follows: npm install --save @siemens/element-translate-ng ``` -An important part of the library is the extraction of translatable keys as a TypeScript interface -as well as extracting a JSON messages file with default translations. The extraction happens on -compiled files. I.e. make sure to run the build first. Then, to run these extractions - -```sh -npx update-translatable-keys -``` - -By default, this will pick of the configuration from a file `element-translate.conf.json`. To -use a different config file, pass as the only argument to the command. - -The config file looks like this - -```json -{ - "files": "dist/@simpl/**/fesm2022/**/*.mjs", - "configs": [ - { - "name": "element", - "locationPrefix": "projects/element-ng", - "keysFile": "projects/element-ng/translate/si-translatable-keys.interface.ts", - "keysInterfaceName": "SiTranslatableKeys", - "messagesFile": "dist/@siemens/element-ng/template-i18n.json" - } - ] -} -``` - -- `files` is a glob pattern for defining the files to scan -- `configs` is an array of configs. For mono-repos building multiple libraries, they can be - separated into different configs. All keys are required: - - `name` is a unique name - - `locationsPrefix` defines the path prefix of the source files, important to distinguish - between different libraries in a mono-repo - - `keysFile` defines the path of the generated TypeScript interfaces file - - `keysInterfaceName` defines the name of the TypeScript `interface` - - `messagesFile` defines the path of the generated messages JSON file +An important part of the translation tooling is the extraction of translatable keys as a TypeScript +interface as well as extracting a JSON messages file with default translations. This is provided by +the separate `@siemens/element-translate-cli` package via the `update-translatable-keys` CLI. See +[Extracting translatable keys](https://element.siemens.io/fundamentals/localization/#extracting-translatable-keys) +for details on how to run it and how to configure it. ## Testing