i18nHelpers('extractUI', sourceRoot, jsonFile)
i18nHelpers('extractErrors', sourceRoot, jsonFile)
i18nHelpers('merge', jsonFile1, jsonFile2)
i18nHelpers('sort', jsonFileA, jsonFileB)
i18nHelpers('register', moduleName, moduleRoot)
i18nHelpers('unregister', moduleName)
| Parameter | Description |
|---|---|
| sourceRoot | String: Path to the source tree to scan (C/C++ and .m files, tests directories excluded) |
| jsonFile | String: Path to JSON translation file destination |
| jsonFile1 | String: Path to the source JSON translation file |
| jsonFile2 | String: Path to the destination JSON translation file |
| jsonFileA | String: Path to the source JSON file to sort |
| jsonFileB | String: Path to the sorted JSON file |
| moduleName | String: The module name whose locale catalog is registered or unregistered |
| moduleRoot | String: The module root directory (typically modulepath(moduleName)), holding locale/<moduleName>-ui-<locale>.json and locale/<moduleName>-errors-<locale>.json |
| Parameter | Description |
|---|---|
| status | Logical: for 'register'/'unregister', true on success. Requesting this output makes the call report a status instead of raising, so no try/catch is needed. |
| message | Character vector: for 'register'/'unregister' with two outputs, an error message when status is false, empty otherwise. |
i18nHelpers provides essential utility functions for managing internationalization files. The main functions include:
-
'extractUI'
: Scans the sources undersourceRootfor translatable user-interface text and writes the text-keyed catalog tojsonFile. The extraction is native (no gettext tooling involved).
-
'extractErrors'
: Scans the sources undersourceRootfor identifier-keyed error/warning templates and writes the errors catalog tojsonFile.
-
'merge'
: Merges two JSON translation files. The entries fromjsonFile1are added tojsonFile2, and entries exclusive tojsonFile2are removed.
-
'sort'
: Sorts and organizes entries in a JSON translation file.jsonFileAandjsonFileBmay refer to the same file if in-place sorting is desired.
-
'register'
: Registers an external module's locale catalog at runtime, so its_()source strings and its<moduleName>:*error templates get localized. The module shipslocale/<moduleName>-ui-<locale>.jsonandlocale/<moduleName>-errors-<locale>.json; the catalog for the current locale is merged immediately and re-merged on every locale change. It is an opt-in call, typically placed in the module'setc/startup.m.
External-module error identifier convention. An error or warning raised by an external module must use the module's own namespace as the identifier prefix, i.e.error('<moduleName>:<mnemonic>', 'literal English template', args...). Only messages that are generic and reusable across Nelson keep theNelson:prefix (these belong to the core catalog, not the module). For a message to be extracted and localized:
- the identifier must start with<moduleName>:(the same name used inmodule.jsonand in the catalog file prefix);
- the template must be a single string literal; a dynamic part is aprintf-style placeholder filled by trailing arguments, e.g.error('mymod:invalidInput', '%s must be a scalar logical.', name)rather thanerror('mymod:invalidInput', [name, ' must be a scalar logical.']);
- each identifier maps to exactly one template (an identifier reused with several different messages is dropped as overloaded). At runtime the inline literal is replaced by the localized template only when it matches the catalog exactly, then the arguments are applied. Generate the catalogs withnmm('i18n', moduleRoot)(orngen.i18n).
-
'unregister'
: Drops a previously registered module catalog and rebuilds the in-memory catalogs, typically from the module'setc/finish.m.
This utility is intended for internal use and may be updated over time.
| Version | Description |
|---|---|
| 1.10.0 | Initial version |
| 2.0.0 | native source extraction (extractUI, extractErrors); convert removed with the gettext tooling |