Table of Contents

Internationalization: the Server Half and the Build Gate

The part of Internationalization that lies outside the client's own bundles: the language preference the server holds and the text it composes in the language a request asks for, the server-originated strings the client words itself — coded errors, error notices and engine notifications —, the four scripts that hold the bundles and the server's codes together and stop npm run build, and the English that reaches the screen in every locale all the same. The bundles, the single switch point and what re-renders on a switch are on that page, and the files on Internationalization Source Code.

The Server Half

The language preference is server-held. GET /api/preference/language answers { success, current, available }, where current is the persisted UserConfig.LanguageCode — default en — and available is the server's own supported list in the order the language menu draws it: en, zh-Hans, zh-Hant, vi, ja. POST rejects a code that is not on the list — matched exactly, letter case included — with 400 and otherwise writes the value and saves the user configuration, which round-trips through the XML user config file. The localStorage key holds only a paint-time hint and loses every disagreement with this value.

Some response text is composed on the server and never passes through a bundle. PresentCatalogService resolves the effective language per request in this order: an explicit ?lang= query, then the request's Accept-Language header, then the persisted preference, then English. Because the header sits above the saved preference, a browser set to a different language than the application would win by default — so the client sends ?lang= explicitly, from a currentLang() helper returning the app locale, on the endpoints whose text is localized server-side: the selected-step info, the execution strip chart, its step-property picker and its colour guide, the mission command entries, catalog and field descriptors, and the step-present key list. The mission controller resolves the same chain into a per-request UI culture and injects it into the command text source, so the culture rides on the request rather than on the thread. Every tag the chain reads goes through PresentCatalogService.Normalize onto a closed set — a zh tag to one of the two Chinese scripts, a primary subtag of vi or ja (split on - or _, as on the client) to vi or ja, anything else to English — because the result names the catalog.{lang}.json file read and is handed to CultureInfo.GetCultureInfo.

Two further server-originated string classes are localized on the client instead:

  • Coded API errors. The rule is that a refusal a user meets in normal use carries a stable code and its interpolation args beside the English message, while a refusal only a broken client meets — a missing body, a malformed id — and the runtime's own exception text stay plain English. The families coded so far are the most frequent refusals (Common/ApiError.cs), the equipment topology's, the step variables' and the step colour trees', the player-lock refusals of the tool house and the solids, the File Explorer page's, a Project root that moved (ProjectDirectoryMoved, from every route that names a file by root), a project replaced since the generation a request states (ProjectGenerationMoved, from every route held to it), the StlFile editor's refused load and the Cutter node's refused return to its mass estimate; a controller outside them can still answer a refusal a user meets in plain English, as its own Anatomy page says. The HTTP helper maps each code it knows onto an apiErrors.* key (API_ERROR_KEYS), and codedErrorText renders a failed response carrying one in the app locale with the server's arguments, an id among them shown by the label the rest of the UI gives it (labelledArgs): a role key by the Roles panel's name, an owner key by the Topology column's part name, a step variable's field by the editor's label, a File Explorer root's name in root by the root's on-screen title. English is passed straight through to the server's own message on purpose, because that message is the English rendering and keeps per-site nuance the generic bundle value flattens — with one exception: the codes of EN_FROM_BUNDLE — the File Explorer page's, whose server English names a root by its internal name (ProjectDirectory) and Duplicate's names in program notation (-Copy-00..-Copy-19), neither of which the screen shows, and numbers a line from 0 as write-lines takes it where the screen numbers from 1, ProjectDirectoryMoved, whose server English names the query parameter and both folders for a REST client, and ProjectGenerationMoved, whose names the header and both generations — render from the English bundle too (see File Explorer Refusals). A code the table does not map renders the server's English in every locale, which the build gate below refuses. A reply that succeeds can carry a coded reason too: where a read it makes meets an exception and the reply is answered all the same — the places that read a released STL mesh back from its file: the STL info dialog wherever an StlFile is edited, and in the Tool House the Upper Beam section's banner, the Cutter node's mass field, the Inner Beam section's area-equivalent core and the Gallery's cell — the field carries { message, code, args } (Common/ReadFailure.cs), with a code where a user meets the reason in normal use and its meaning is fixed — so far one, the file gone, StlReleasedFileGone — and a null code and args for every other reason, which stays English. readFailureText words it through the same table, falling back to the server's English message for a null code and in English. A refusal whose argument is such a reason — ShankMassReturnRefused's reason — has it worded the same way by labelledArgs. Where the bundle's sentence goes on after the reason (toolhouse.upperBeam.readError), readFailureText(failure, true) leaves off the last period of an uncoded English reason, so the banner reads …end of the stream。請選擇…, not .。 or ...
  • Error notices. A failed request's HttpError carries the server's sentence alone as its message (a coded one already in the app locale); the status stays in status and in the console (name is HttpError <status>), never on the screen. A toast or banner that names what failed joins that context to the sentence through errorIn(context, message) (wwwroot-src/src/utils/errorIn.ts, the bundle key common.errorIn): : in English and Vietnamese, the full-width : in Chinese and Japanese. The context keys (ctx*, err*, toolhouse.error.*) are bare phrases, and a context that is itself joined — the Control Tree's slave title before a panel's own context — is joined the same way, so a Japanese notice reads 工具番号 1 / カッタ:全般:….
  • Engine notifications. Session messages arrive with a structured id and English text. The client swaps in an engineMessages.<id> bundle entry, but only when the wire text agrees with the English bundle entry for that id: a templated message must match the canonical English template exactly before its arguments are re-interpolated, and an untemplated one is swapped only when the bundle entry has no interpolation holes. Any mismatch — an id emitted with different templates at different sites, or an engine built against a different bundle — falls back to the wire English rather than rendering wrong text. The English engineMessages values are therefore load-bearing code, not a description of the translated ones. The arguments travel as text (SessionSinkDtoMapper.Template), each rendered in the invariant culture with its hole's own alignment and format. A share a message prints — a channel's synchronous energy, a duty, a correlation — the engine prints itself with PercentText.OfRatio (0.85%, <0.01%), never through a {0:P2} hole, whose invariant 0.85 % would differ: the notification English shows, its arguments and every translation read it alike.

The step-present labels have a third home again: they ship beside the executable as catalog.{lang}.json files that overlay translations on top of the live English attribute data. English never comes from those files, and a missing file, a missing key or a parse failure simply means English. The translations in them are generated from glossary.yaml, described below, so a step-field name is changed there and not in a catalog file. A field whose values are an enum's members — the two cutter zones, StressCriticalZone and StressOnsetZone — has the names of its values in the same files (valueLabels, keyed by the value's number: a cutter zone's 刃區), generated from the same glossary, each from the entry whose context is the enum's own name (CutterBeamZone), since the same English names other things elsewhere (Flute, None, Taper); a value the file does not name reads in English, which comes from the enum itself.

The Glossary and the Build Gate

Four Node scripts lint the bundles and what reaches them. wwwroot-src/package.json defines lint:i18n as census.mjs, then lint-glossary.mjs, then lint-engine-messages.mjs, then lint-api-error-codes.mjs, and build as lint:i18n followed by quasar build — so any of the four failing stops npm run build. The release builds — the web service's own front end and the installed HiNC's — do not run npm run build. They run lint:i18n as a step of its own and only report its failure, so the bundle ships all the same, with a missing translation in English and a wrong value as it is. The installed HiNC's build then runs the type check, which does stop it on a key missing from a locale. The development server runs none of them.

lint-glossary.mjs takes its locale list from SUPPORTED_LOCALES in the i18n module, bundles each locale's index through esbuild, flattens the message trees into key/value maps, and applies five checks to them and a sixth to the server's step-field catalogs, any one of which fails the lint:

  1. Locales and key isomorphism. Every listed locale needs its folder and index file and, English aside, a literal import() of that folder in LOCALE_LOADERS, and a folder holding a bundle must be listed: quasar build notices neither omission, and the locale then never shows. One that LOCALE_LOADERS leaves out has no more to show for it than a console warning and, when it is picked from the menu, the toast saying its texts did not load; a bundle the list leaves out, in a language normalizeLocale has no rule for, has not even the warning — normalizeLocale gives its code null, and applyLocale applies English in its place — only the toast when it is picked. A bundle that does not build is a finding too. Every other locale's flattened key set must then equal English's, compared in both directions, so an extra key fails as loudly as a missing one.
  2. Bidirectional key integrity. Every bundle-shaped string literal under the source tree — excluding the bundles themselves — must resolve to an English key, and every English key must be referenced from somewhere. A literal naming a namespace prefix counts as a reference to everything beneath it; a template literal with an interpolation hole is expanded into a wildcard, which is how tree.mission.kind.${kind} is matched; and @:linked.key references inside bundle values count as well. A double-quoted literal in a Vue template is treated as a key only when its attribute is one of the four the check knows to be key-valued, so an expression attribute whose local variable happens to share a namespace name is not mistaken for one. The orphan half is what makes the check bidirectional, and its allow-list is currently empty.
  3. Shape preservation. Never-translate tokens present in an English value must survive verbatim in every other locale's value — product and brand names, file formats and unit symbols by literal match, and NC codes, controller parameter names and function-key shortcuts by pattern. Placeholder sets must match in both directions, so a translated value can neither lose a placeholder nor invent one.
  4. Per-locale vocabulary. An adjudicated forbidden-term table per locale, each entry naming its reason and, where there is a single one, its replacement, plus a check for a value identical to its English source that still holds something to translate — for a Chinese value, any two Latin letters in a row. Both carry narrow exemptions: named keys where a term is used in a different sense, and an identity set per locale for values that legitimately are the identifier.
  5. Message form. Every non-English value must be Unicode NFC; every value vue-i18n renders — all but the English engine messages, whose wire English renders in their place — must compile under its message compiler, so a bare @ or an unpaired brace fails the lint (a literal @ is written {'@'}); and a Vietnamese or Japanese value must keep its English value's number of plural forms, separated by |.
  6. Step-field catalogs. Every name and short name in the catalog.{lang}.json files of the HiNc-Resource package's StepPresentCatalog folder, and every label of an enum-typed field's values (valueLabels, a cutter zone's 刃區), for each locale but English, must be NFC and clear of that locale's forbidden-term table. The folder is looked for the way lint-engine-messages.mjs looks for its catalog. No folder, or no file for a locale, is no finding — a checkout of the web service alone has none to check, and the server serves a locale without its file in English — while a file that does not parse is one.

Vietnamese, the one translated locale in Latin letters, is read in its own way. A never-translate token or code counts in a Chinese or Japanese value wherever it occurs, but in a Vietnamese one only as a word of its own, with Unicode letters in its boundaries, so the capital N of Nước does not stand in for the newton symbol N. The vi forbidden-term table, its patterns bounded the same way since \b knows only ASCII letters, bans Han characters and CJK or fullwidth punctuation; a tone mark in the newer place on an open oa, oe or uy syllable (hoá, tuỳ, khoẻ), where the bundles keep the traditional placement on the first vowel that Microsoft's and Quasar's Vietnamese UI use (hóa, tùy, khỏe); and three readings the vocabulary table rules out — chương trình điều khiển for the Control Tree (cây điều khiển), thành phần lỗi or số hạng lỗi for an error term, a deviation (thành phần sai số) rather than a mistake, and bầu kẹp for the holder (đầu kẹp). A Vietnamese value identical to its English is a finding unless nothing is left to translate once tokens, codes, placeholders, numbers and units are set aside (RTCP, {n} mm), or its key is in the vi identity set — a set of its own, since a locale in Latin letters keeps far more English than a Chinese one and its exemptions must not pass a Chinese value. NFC means precomposed letters: a value holding a letter stored as a base letter followed by combining marks is a finding. Vietnamese does not tell one from many, so its plural forms usually repeat one text, a zero form aside, but their number stays the English value's.

Japanese is read as the Chinese locales are: a token or code counts wherever it occurs (G54の値), and a value identical to its English is a finding when it holds two Latin letters in a row, unless its key is in the ja identity set. Its forbidden-term table starts with characters. A Han character outside JIS X 0208 — the set read once from Node's Shift_JIS decoder without the NEC and IBM extension rows of Windows-31J, whose kanji are mostly Traditional forms (增, 寬, 橫, 黑); on a Node built with small ICU the lint fails rather than skip the check — is a Chinese one, Simplified or a Traditional form Japanese never adopted; a 旧字体 form from a table of pairs (轉 → 転, 數 → 数, 沒 → 没 …) is a Traditional or pre-war spelling; a few JIS characters Chinese writes where Japanese does not (后, 无, 气, 决 …), half-width katakana, full-width letters or digits, and the full-width comma and full stop , . are findings too. Then words: Chinese words that read like Japanese (程式, 檔案, 預設, 載入, 刀具, 進給, 工件 …), each with the Japanese to write where there is one; function words in kanji that Microsoft's Japanese style guide writes in kana (下さい, 出来, 既に, 全て, 又は …), each pattern stopping short of a correct word with the same characters (変更に, 一致し, 及びます, 出来高); loanwords written with the final long-vowel mark that JIS Z 8301, the spelling of the machine-tool makers' manuals, drops, from a table of spellings (パラメーター for パラメータ, ホルダー for ホルダ, メモリー for メモリ); and six readings the vocabulary table rules out — 制御プログラム or 制御ツリー for the Control Tree, エラー項 for an error term, ツールホルダ for the holder, 取付け点 for a mount, 衝突 for a collision and プレイヤ for the player. Japanese has no plural either, so its plural forms repeat one text, a zero form aside, and their number stays the English value's.

The tables the third and fourth checks read are written at the top of the script itself. glossary.yaml, the large term list that sits beside the bundles, is no input to the lint: the lint never reads it and the application never imports it. Its Chinese values were harvested from the legacy localization corpus by .ai/harvest-i18n.py, whose adjudication tables, not the file, hold its rulings on a harvested term; that full harvest is retired, and running it again needs the legacy repositories cloned back beside the web service first. The step-field entries (context MachiningStep), whose legacy source is gone, and the Vietnamese and Japanese values, which never had one, are kept in the file by hand, and a full run carries them over. What the file does feed is the server: harvest-i18n.py --present-catalog, which needs no legacy source, generates the step-field catalogs StepPresentCatalog/catalog.{zh-Hant,zh-Hans,vi,ja}.json from it, so a step-field name — a finding of the sixth check included — is changed in glossary.yaml, never in a catalog, which the next run would overwrite.

census.mjs guards the opposite direction — text that never became a key. It scans the same tree for user-visible English string literals reached through display-named template attributes, display-named object properties, notification and dialog shorthands, and prose text nodes; subtracts a classified allowlist of concrete text-and-file pairs; and compares what is left, per file, against a baseline. The gate fails only when a file's residual count rises, so cleanup can land incrementally — but the baseline is currently empty, which allows zero residual strings in any file and makes the effective rule that a newly hard-coded display string fails the lint unless it is added to the allowlist with a reason. Allowlist entries whose file field is a glob or a brace list are classification notes rather than matchers; only concrete paths participate.

lint-engine-messages.mjs holds the English engineMessages entries to the engine that emits them. It reads the catalog of emit sites the engine ships in the HiNc-Resource package — each templated site's id and template — and fails on a templated English entry no site carries, on one that matches none of its id's templates byte for byte, and on a listed id the engine emits with two different templates: in each case the engine-notification swap above falls back to the wire English, in every locale, for some or all of that id's messages. No catalog found is a failure, not a skip.

lint-api-error-codes.mjs holds the server's coded API errors to the client's code table. It scans the web service's C# for code = "…" literals, with the comments blanked first by a one-pass lexer that keeps strings and character literals, so a code quoted in an XML doc is no payload, and fails on a code API_ERROR_KEYS does not map unless its own short list, OWN_TEXT, names it with the reason the client reads it another way: InvalidCredentials, which the login page reads itself; MechanismRefused, the engine's own untemplated text, shown as sent; and two whose bodies carry no text to translate (content_hash_mismatch, script_compile_error). A code written as an interpolated, verbatim or raw string fails as unreadable, an OWN_TEXT entry the server no longer sends fails as stale, and no code found at all is a failure, not a pass. A code merely quoted elsewhere in the client counts for nothing: only a table entry is a translation, and the glossary lint's key checks then hold that entry's key to every bundle. Not seen: a code built at run time or passed through a constant or an argument — an engine refusal's id, which renders through the engine-message bundles, among them — and the capitalised Code of the equipment roles' checks, which the Roles panel reads as mech.roles.check.* keys.

A build with HINC_PRODUCT_SPA set compiles another product module in place of the web service's own (Hosting from another project). With the variable set, lint-glossary.mjs also loads that folder's bundles, one per locale, which its boot file merges into the app's, checks them as part of the app's and scans the folder's files with the source tree, and adds two checks. A module with strings of its own must carry a bundle for every listed locale and merge each in its boot file, because a locale left out breaks no build and only shows that module's strings in English; and no top-level namespace of the module's may repeat one of the app's, because the merge is deep and whichever side merges last wins: the module's strings overwrite the app's in English and in the locale applied at boot, and the app's own bundle overwrites the module's in a locale loaded later — either way a string changes with no sign. census.mjs scans the folder too, against an allowlist and a baseline the folder keeps for itself, so the module's exemptions never land in the web service's own lists, and lint-api-error-codes.mjs scans the C# of the project the folder sits in against the same code table as the web service's.

Strings Outside the Bundles

Two classes of user-visible English render in every locale — one because an interpolation hole hides it from the census, which discards any literal containing one, and one because the allowlist deliberately keeps it:

  • The geometry and topology editors' error prefixes. Those editors emit their failure context as a template literal that leads with the type name and the operation, so the leading phrase is English whatever the locale. The allowlist records the family as a ledger note rather than as matched entries.
  • The API-error default. The generic fallback message in the HTTP helper is allowlisted deliberately, on the grounds that it sits in the same stream as the server's own English messages.

A third class is untranslated by design rather than by escape: the dynamic label text on a Control-Tree node — a file-backed path, an engine type name, and the user's own words inside a server-composed mission title — and the identity strings the allowlist classifies alongside it, which are backend type names rendered inside a translated sentence, axis and unit column headers, and brand names. The role-label half of that same allowlist class is a different case again: stored English that never reaches the screen at all, because a labelKey always resolves ahead of it.

Engine notifications carry a fourth through their arguments: the client fills the bundle's template with the arguments as they arrive, so an argument that is English text rather than a number stays English inside the translated sentence — the one argument of Cutter-ShaperProfile--AptRefused, the engine's self-agreement note naming the relations a flute profile fails, reads in English in the middle of the Tool House's Flute Profile banner in every locale.

See Also