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
codeand its interpolationargsbeside the Englishmessage, 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 anapiErrors.*key (API_ERROR_KEYS), andcodedErrorTextrenders 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 inrootby 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 ofEN_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 aswrite-linestakes it where the screen numbers from 1,ProjectDirectoryMoved, whose server English names the query parameter and both folders for a REST client, andProjectGenerationMoved, 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 nullcodeandargsfor every other reason, which stays English.readFailureTextwords it through the same table, falling back to the server's Englishmessagefor a null code and in English. A refusal whose argument is such a reason —ShankMassReturnRefused'sreason— has it worded the same way bylabelledArgs. 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
HttpErrorcarries the server's sentence alone as itsmessage(a coded one already in the app locale); the status stays instatusand in the console (nameisHttpError <status>), never on the screen. A toast or banner that names what failed joins that context to the sentence througherrorIn(context, message)(wwwroot-src/src/utils/errorIn.ts, the bundle keycommon.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 EnglishengineMessagesvalues 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 withPercentText.OfRatio(0.85%,<0.01%), never through a{0:P2}hole, whose invariant0.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:
- Locales and key isomorphism. Every listed locale needs its folder and index file and, English
aside, a literal
import()of that folder inLOCALE_LOADERS, and a folder holding a bundle must be listed:quasar buildnotices neither omission, and the locale then never shows. One thatLOCALE_LOADERSleaves 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 languagenormalizeLocalehas no rule for, has not even the warning —normalizeLocalegives its codenull, andapplyLocaleapplies 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. - 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.keyreferences 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. - 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.
- 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.
- 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|. - Step-field catalogs. Every name and short name in the
catalog.{lang}.jsonfiles of the HiNc-Resource package'sStepPresentCatalogfolder, 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 waylint-engine-messages.mjslooks 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
- Internationalization — the bundles these strings render through, the boot file and the single switch point
- Internationalization Source Code — the lint scripts, the server's language code and the client files that word these strings
- Translation Remarks — the terminology contract the glossary lint holds the bundles to
- File Explorer Refusals — the first page whose refusals a user meets carry codes under the revised rule, English included from the bundle