In Codex v1.9.0, we introduced a new useI18n composable to simplify the way that translatable strings are used in components. Some documentation for how to use the useI18n composable can be found here. However, we could stand to improve the current workflow somewhat.
- Every time a new translatable string is used in a Codex component, there is an expectation that the same string will be added to MediaWiki's i18n files simultaneously. Codex now depends on the MW codebase (implicitly) in a way that it did not in the past.
- Correct usage is not enforced by any automated linting or testing; "failure mode" silently defaults to English text.
- Forgetting to add new messages back to MW could result in broken interfaces in production Wikipedia for non-English-speaking users.
- There is no single place within the Codex docs that keeps track of all i18n messages (and their default values) used across all components.
Recommendations
We should institute a new workflow for working with translatable strings in Codex that attempts to address the issues listed above. Ideally, we would automate as much of the process as possible. Some specific things we could do:
- Consider adding all new messages to the Codex changelog on each release. When a new Codex release is deployed to MW, cross-reference the list of new messages with MW's i18n JSON files. This process could be added to the Codex release instructions.
- Consider creating a page in the Codex docs that lists all current i18n strings and their default values, as well as which component(s) they are used in. This could be displayed in a table.
- Consider linting/testing against every call to useI18n in the Codex codebase; using a new message key without defining it in the proper place (where?) would result in a failure.
- Consider moving the i18n JSON files which define the component messages into the Codex itself (we'd still want them integrated into TranslateWiki however). This may be necessary if we want better linting/testing for i18n messages.
Next Steps
- The team has discussed the above recommendations and agreed on what to implement
Codex updates
- A new constant has been added to the constants.ts file – this should be an array of strings corresponding to each message key currently defined with useI18n
- A new type is derived from this constant and used in the type definition for the useI18n composable. This means that Typescript should generate an error if useI18n is called with a new message key that has not yet been added to the list in the constant
- A build script has been added to the Codex package that generates a JSON file from the new constant which contains all message keys currently in use; this file should be included in the published version of the package
MediaWiki updates (these may be moved to a follow-up task in the future)
- The new message key definition file needs to be added to the files copied over into MW from Codex in foreign-resources.yml
- A unit test should be added in MW Core that tests the contents of this file against the message keys in MW – any key present in this file but not present in the en.json or qqq.json files should cause an error. This test should run in CI, and it should prevent a new Codex release from being added to MW unless all necessary message keys are added in MW core
- ResourceLoader should use this new file to automatically deliver the appropriate message keys when Codex components are loaded