Configuration
The module reads its options from its entry in antelope.config.ts.
"dms-lang": {
source: { type: "package", package: "@antelopejs/dms-lang", version: "^0.2.0" },
config: {
editable: true,
},
},
Module options
| Option | Type | Default | Description |
|---|---|---|---|
editable | boolean | false | Allows the running process to create, rename and delete workspaces, add and remove languages, and write keys and translations. When false, every write route answers with a read-only error and the pages show the texts without editors. |
workspacesDir | string | the module's i18n-workspaces folder | Where the workspaces you create are stored. A relative path is resolved against the working directory of the backend process. Point it outside the module's install folder (for example a folder of your project) so a reinstall or upgrade of the module keeps them. |
editable only where people translate (development, a staging back office). A production process that serves the public locale files usually stays read-only.Frontend module options
The Project files workspace edits the locale files of the frontend modules flagged as the application layer. Set the flag in the options of AddFrontendModule:
| Option | Type | Description |
|---|---|---|
dmsI18nAppLayer | boolean | Marks the frontend module's locale files as the writable project files. Other frontend modules (the DMS, installed modules) stay read-only in the Installed modules workspace. |
Locale files follow the DMS adapter convention: one JSON file per namespace and locale, named <name>-<xx-XX>.json (such as app-en-GB.json or lang-fr-FR.json). A file named otherwise (app-it.json, en.json) is ignored.
Without a layers directory, Lang scans the module's i18n/locales directory recursively. When layers exists, Lang scans layers/*/i18n/locales instead, including subfolders of each locale directory; it ignores the module's root i18n/locales, even when layers is empty. The registry groups files by the two-letter language code: en-GB and en-US both contribute to en, not separate regional locales.
Project files
A flagged module may hold any number of files per language: app-en-GB.json alone, or one file per domain such as demo-en-GB.json, crm-en-GB.json and team-en-GB.json. They are merged per language, in file-name order (a later file wins on a key both define), after the files of lower-priority flagged modules.
A write from the Project files workspace goes, for each language, to:
- the file that defines the key (the one whose value shows when several do), so an edit lands where the key already lives;
- for a key no file of that language defines yet, the file holding the longest part of its namespace:
crm.deals.titlegoes to the file that already hascrm.deals, else to the one that hascrm; - when no file shares its namespace, the last file named exactly
app-<xx-XX>.jsonin merge order; a domain file such asapp-crm-en-GB.jsonis not an app fallback; - without an exact app fallback, the last file of the language in merge order.
A renamed key stays in the file that defined it. Add a language by adding a <name>-<xx-XX>.json file next to the others.
Storage and public URL
| What | Where |
|---|---|
| Workspaces you create | <workspacesDir>/<workspace>/ (default: the module's i18n-workspaces folder), one <locale>.json per language |
| Public files | GET <apiBaseUrl>/i18n/<workspace>/<locale>.json, open to any origin, Cache-Control: no-cache |
| Public origin | The DMS apiBaseUrl (the dev server's origin in development) |
| Through the dashboard | The module declares /i18n/** to the frontend server as a backend prefix without a session (backendProxies: [{ path: "/i18n/**", auth: "none" }]), so the same files also answer on the dashboard's origin |
Changing workspacesDir does not move existing workspaces. Copy their directories, including manifests, to the new location before switching the configuration. Give the backend process read access and, when editing is enabled, write access; use persistent storage and keep backups.