Skip to content

feat(viewer): translatable UI texts: strings table, locale and strings props - #6

Open
mkroemer wants to merge 3 commits into
p10node:mainfrom
mkroemer:ui-strings
Open

mkroemer wants to merge 3 commits into
p10node:mainfrom
mkroemer:ui-strings

Conversation

@mkroemer

@mkroemer mkroemer commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Hosts can translate the viewer or override individual labels without forking its components. A typed Strings table covers the shared chrome and dialogs, DOCX/XLSX/PPTX views, comments, drawing placeholders, collaboration labels and Visio import labels. Partial overrides inherit an enclosing StringsProvider or English. Print, PDF and HTML export carry the same table into their separate React roots.

English is the only default language bundled. Standard German is an explicit package import using de-DE formatting:

import { DocViewer } from '@p10node/office-engine'
import { de } from '@p10node/office-engine/locales/de'

<DocViewer src={file} strings={de} />

locale is an optional BCP 47 number/date formatting tag; it does not choose or load UI translations. Without an override, dates and grouped counts retain browser formatting; page/slide numbers and measurements retain ASCII digits and decimal points. The prop takes precedence over strings.locale, and malformed tags fall through to a valid table/inherited tag safely. Count callbacks receive numbers for pluralization and an optional final formatting tag. The API docs show hoisted partial overrides, custom tables and US/British English variants.

Reconstructed on main fb718881, preserving its security, save and Visio changes. German UI labels survive export; changing strings no longer resets spreadsheet comment navigation.

Validation includes a frozen Bun1.4.4 install, typecheck, production/companion builds and package checks. The correction passes710 unit tests,24 source/embed/production browser checks, and11 repeated packed-package browser checks. Earlier coverage also exercised49 source-browser cases. Independent Claude Opus5.5 high review approved the corrected candidate after build/runtime/package verification. Browser checks include default/invalid locales, provider inheritance, live switching, singular/numeric callbacks, Visio and separate print/export roots; downloaded HTML was reopened and PDF text inspected. Native OS print-dialog interaction and the entire unrelated browser suite were not tested. Core/transport diagnostic errors and locale-aware numeric-input parsing remain documented exceptions/separate work.

Display notes: Sheets/hidden-sheet counts and both paste-limit counts now use the same locale formatting as other grouped counts. Intl percent formatting can round an exact half differently from Math.round (for example0.285); preset zoom values are unaffected.

Upstream integration note: this candidate was reviewed and tested against fb718881 (v0.15.0). Since that validation, main advanced to 4a78390 (v0.16.0), with overlapping editor changes. This push publishes the reviewed fixes; resolving the new merge conflicts and validating that integration are still pending.

@pierreneter pierreneter left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, the typed table and the parity test are a good base.

Not ready on its own yet. Merged alone it ships a half-translated viewer and docs ahead of the code:

  • With locale="de" only the top bar and the shared dialogs are German. The File menu is still the literal "File" (src/react/file/FileMenu.tsx:186), and the toolbars, context menus, find bar and status line stay English. 130 of the 219 keys are read by nothing at this commit.
  • README.md and docs/api.md say every text comes from the table, and the examples use docx.status and xlsx.addSheet, which only exist in Strings from #8 on. The file: { menu } example has no effect here.

Either of these would do:

  1. Move the three feat(docx|xlsx|pptx): ... read their texts from the strings table commits from #8 into this PR (my preference: one PR, one complete feature), or
  2. Limit the docs and examples here to what this PR converts.

Smaller points: de is always bundled (about 2.9 KB gzip), which is fine for now. The table is Swiss German with de-CH number grouping; please name that in the docs, since locale="de-DE" falls back to English without a word. A test that renders one component in German would be good.

@mkroemer

Copy link
Copy Markdown
Contributor Author
  • Included the three DOCX/XLSX/PPTX translation commits from feat(viewer): headless mode and a controller for host-drawn controls #8, completing translation of toolbars, menus, dialogs, find/replace and status text. The previously unused keys now have consumers; the reference audit accounts for all 592 current keys.
  • Added XLSX drawing placeholders and chart-type labels to the translation table.
  • Made English the only bundled default. German is available through @p10node/office-engine/locales/de, passed as strings={de}, using standard German spelling and de-DE formatting.
  • Updated the README and API docs with optional imports, overrides, custom languages and embed examples. The regional override example uses US/British English.
  • Added rendered translation and override coverage.

I also fixed unsafe fallback for unknown locale names, stale comment translations after switching languages, untranslated PPTX comment locations, and repeated web-component load events after UI updates.

Verification: 549 unit tests, 15 localization/embed browser tests, typecheck, build and package checks pass locally. Verified that default viewer and embed bundles exclude German. Current main is merged.

Locale-aware numeric input is tracked separately in #17.

@pierreneter pierreneter left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, the earlier points are done: every key has a reader now, the docs examples match the table, German is an opt-in import with standard spelling, and there are rendered tests in German.

Before merge (line numbers are at acd8b16):

  1. src/react/strings/en.ts:7: the default table sets locale: 'en-US', and dates and counts are now formatted with it. Before, they used toLocaleString() with the browser's locale. So for every host that passes nothing, a vi-VN or en-GB browser now shows 5 March as 3/5/2026, 2:00:00 PM in Document details, comment times and tracked-change tooltips. The default output should stay as it was; leaving the default table's locale undefined, so Intl takes the browser's, would do it.
  2. Rebase onto main. v0.14.0 added Visio, and this now conflicts in docs/api.md, src/react/DocViewer.tsx and src/react/file/importFile.ts. The table needs a from.visio text, and file.unsupported should name Visio, in both en and de.
  3. src/react/file/print.tsx:182: print, PDF and HTML export render the pages in their own createRoot with no StringsProvider, so useStrings() gives English there. German UI, a slide with an EMF picture: EMF-Bild on screen, EMF image in the export.
  4. src/react/strings/index.tsx:41: strings.locale goes straight into Intl.NumberFormat during render. A host that passes its app locale as de_DE gets a RangeError and a blank viewer. Please validate the tag once and fall back, rather than throw.

Worth settling now, since these become API:

  1. The locale prop and attribute, LOCALES and LOCALE_NAMES: the only valid value is the default. Anything else, de-DE included, is silently English, and it does not select the formats either (that is strings.locale). Either drop locale, or make it the BCP 47 formatting tag that defaults to the browser's. The second also solves 1.
  2. Count texts receive strings that are already formatted (docx.status, xlsx.status, usedRangeValue, hiddenSheets, pptx.status), so a table cannot choose a plural form: the German one shows 1 Wörter and 1 Zeilen × 1 Spalten. Passing the numbers keeps that open. Changing the signature after a release breaks host overrides.
  3. src/react/DocViewer.tsx:140: DocViewer always mounts its own StringsProvider built from English, so an enclosing <StringsProvider strings={de}> is ignored. IconsProvider composes with the outer one; this should too.

Non-blocking:

  • src/react/xlsx/XlsxView.tsx:312: the comment-host effect now depends on str, and its local counter starts again when the strings object changes identity (an inline strings={{...}} does that on every host render). The next "go to comment" on the same sheet can then reuse a goto.n the grid has already seen and do nothing. Reading the hint lazily from the comments controller would take str out of those three effects (DocxView.tsx:723, XlsxView.tsx:358, PptxView.tsx:636).
  • The provider memoises on object identity, and every docs example passes an inline object, so each host render rebuilds the table and re-renders every consumer. A content key (as useCollab does with optsKey) or a hoisted object in the examples.
  • Main-thread error texts stay English (HTTP 404 while fetching …, Document is still syncing) and are not among the documented exceptions.
  • Helpers default their strings argument to English (styleChoices(…, t = en), sheetPrintable(…, t = en)), so a call site that forgets it compiles and renders English. Required parameters would catch that.
  • The PR description still says 'en' | 'de', Swiss spelling, and that the DOCX / XLSX / PPTX views follow in later PRs.
  • docs/api.md:66: the new locale row is out of line with the table's columns.

@mkroemer

Copy link
Copy Markdown
Contributor Author

Addressed the localization follow-ups:

  • locale now controls BCP 47 formatting, with validation and safe fallback.
  • Partial overrides inherit the enclosing provider; count callbacks receive numbers for pluralization.
  • Print, PDF and HTML exports receive the active translations.
  • Added Visio labels and the remaining XLSX clipboard toasts.
  • Preserved existing default formatting. German remains an explicit import.

Updated the docs and description, including the small count-formatting and exact-half zoom-rounding differences. Build, typecheck, browser/export and packed-package checks pass locally.

Upstream integration note: this candidate was reviewed and tested against fb718881 (v0.15.0). Since that validation, main advanced to 4a78390 (v0.16.0), with overlapping editor changes. This push publishes the reviewed fixes; resolving the new merge conflicts and validating that integration are still pending.

The texts upstream added meanwhile go through the strings table, in
English and German: Duplicate sheet (now a real copy of the sheet), the
custom number format picker, the fill and merged-paste limits, the
message after a merge drops values, the cell field's label, and the
unsupported-file error saying what the file is instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants