web: localization

This package contains all the localization strings needed by all of the other packages in our
application, and provides tooling for making them available as JavaScript translation catalogs
suitable for `lit-localize`. It does this by scanning the source trees of all of the packages and
assembling the complete list of translatable (and already translated) strings into the `./xliff`
folder.

Commands provided:

- extract-locales: extracts any string tagged as translatable (i.e., with the `msg(...)` syntax) and
  integrates any newfound strings into the existing XLIFF files. Also: reprocesses the
  `sourceLocale` file to create a pseudolocale for testing purposes. (This must be done
  sequentially, as the `sourceLocale` file must be built before the conversion takes place.)
- build: Convert XLIFF to Typescript, compile, lint, and format. The `lint` pass is especially
  important as it enforces the "backquotes to doublequotes when no template in use" rule, and the
  `format` pass must always come last to ensure our committed code matches our standard.
- clean: Delete the `dist` and `src` folders, as well as the constructed `.mjs` file for
  pseudolocalization.

Due to the circular nature of translation's dependencies (*every* package must be scanned for new
strings, and if there are new strings, *every* package must then be rebuilt), extraction is not
performed automatically. This introduces the risk that a developer may not run the extraction and
test as needed. The reminder in the GitHub pull request template is there for a reason.

If you add a new package to the monorepo and it has strings that need translating, you must add it
to the list of `inputFiles` scanned in `lit-localize.json`.

---

(p.s.: The content you just read is also in the README file for this package.)
This commit is contained in:
Ken Sternberg 2024-01-09 14:14:25 -08:00
parent 5d3d2a2548
commit fef7892821
4 changed files with 36 additions and 1 deletions

View File

@ -2,6 +2,7 @@ module.exports = {
pipeline: { pipeline: {
"extract-locales": [], "extract-locales": [],
"build-locales": [], "build-locales": [],
"clean": [],
"build-locales:build": [], "build-locales:build": [],
"build-locales:repair": [], "build-locales:repair": [],
"rollup:build": [], "rollup:build": [],

View File

@ -8,6 +8,7 @@
"build-locales": "lage build-locales", "build-locales": "lage build-locales",
"build-locales:build": "lage build-locales:build", "build-locales:build": "lage build-locales:build",
"build-locales:repair": "lage build-locales:repair", "build-locales:repair": "lage build-locales:repair",
"clean": "lage clean",
"rollup:build": "lage rollup:build", "rollup:build": "lage rollup:build",
"rollup:build-proxy": "lage rollup:build-proxy", "rollup:build-proxy": "lage rollup:build-proxy",
"rollup:watch": "lage rollup:watch", "rollup:watch": "lage rollup:watch",

View File

@ -0,0 +1,33 @@
web: localization
This package contains all the localization strings needed by all of the other packages in our
application, and provides tooling for making them available as JavaScript translation catalogs
suitable for `lit-localize`. It does this by scanning the source trees of all of the packages and
assembling the complete list of translatable (and already translated) strings into the `./xliff`
folder.
Commands provided:
- extract-locales: extracts any string tagged as translatable (i.e., with the `msg(...)` syntax) and
integrates any newfound strings into the existing XLIFF files. Also: reprocesses the
`sourceLocale` file to create a pseudolocale for testing purposes. (This must be done
sequentially, as the `sourceLocale` file must be built before the conversion takes place.)
- build: Convert XLIFF to Typescript, compile, lint, and format. The `lint` pass is especially
important as it enforces the "backquotes to doublequotes when no template in use" rule, and the
`format` pass must always come last to ensure our committed code matches our standard.
- clean: Delete the `dist` and `src` folders, as well as the constructed `.mjs` file for
pseudolocalization.
## User notes:
Due to the circular nature of translation's dependencies (*every* package must be scanned for new
strings, and if there are new strings, *every* package must then be rebuilt), extraction is not
performed automatically. This introduces the risk that a developer may not run the extraction and
test as needed. The reminder in the GitHub pull request template is there for a reason.
## Maintenance note:
If you add a new package to the monorepo and it has strings that need translating, you must add it
to the list of `inputFiles` scanned in `lit-localize.json`.

View File

@ -12,7 +12,7 @@
"clean:dist": "rimraf dist scripts/*.mjs", "clean:dist": "rimraf dist scripts/*.mjs",
"clean:build": "rimraf src", "clean:build": "rimraf src",
"clean": "npm-run-all --parallel clean:dist clean:build", "clean": "npm-run-all --parallel clean:dist clean:build",
"extract-locales": "run-p localization:extract localization:pseudolocalize", "extract-locales": "npm-run-all --sequential localization:extract localization:pseudolocalize",
"lint:lint": "eslint . --max-warnings 0", "lint:lint": "eslint . --max-warnings 0",
"fix:lint": "eslint . --max-warnings 0 --fix dist/locale-codes.js", "fix:lint": "eslint . --max-warnings 0 --fix dist/locale-codes.js",
"fix:prettier": "prettier --write ./src/**/* ./package.json ./lit-localize.json", "fix:prettier": "prettier --write ./src/**/* ./package.json ./lit-localize.json",