Skip to content

docs(localization): document translate CLI key extraction #2247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
spike-rabbit wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(localization): document translate CLI key extraction #2247

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions docs/fundamentals/localization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,3 +264,51 @@ Note that this hash key will only be appended to the translation based JSON file
### Translatable keys in Element

<si-docs-type name="SiTranslatableKeys"></si-docs-type>

### 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.
42 changes: 5 additions & 37 deletions projects/element-translate-ng/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading