Skip to content

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

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

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

Conversation

@mkroemer

Copy link
Copy Markdown
Contributor

Builds on #5 (icons), which builds on #4 (theming). Until those are merged this PR shows their commits too; the strings part is the last commit.

This lets a host show the viewer in another language, or change single texts, without forking the components.

The viewer's texts come from one typed table, Strings (src/react/strings/en.ts), with a complete German table next to it (de.ts). DocViewer, mount() and <office-viewer> take locale ('en' | 'de', default 'en') and strings, a partial table merged over the locale key by key:

<DocViewer
  src={file}
  locale="de"
  strings={{
    file: { menu: 'Ablage' },
    docx: { status: (page, pages, words) => `${page}/${pages} · ${words} Wörter` },
  }}
/>

A text that depends on a count or a name is a function, so each language can put the parts in its own order. StringsProvider and useStrings() give standalone views the same texts, and a host's own components can read them too. Numbers and dates in the UI go through Intl with the table's locale. With the default locale the output is unchanged, so the existing tests keep passing as they are.

This PR converts the parts every file kind shares: the top bar, the details rows, the common dialogs, the zoom control, the shared toolbar controls, the source pane and the picture view. The groups the document, sheet and slide views need are in the table already, so converting those views follows in three separate PRs (DOCX, XLSX, PPTX), to keep each one reviewable.

The German table uses Swiss spelling (ss for ß), which is what I need; switching it to German-German spelling is a one-line test change plus a search and replace if you'd rather have that as the default.

test/strings.test.ts checks that every locale has all keys of en, and no empty texts. bun run typecheck, bun test and the e2e suite pass in CI.

🤖 Generated with Claude Code

…s props

The viewer's texts come from one typed table, `Strings` (src/react/strings/en.ts),
with a complete German table next to it (de.ts, Swiss spelling, Word / Excel /
PowerPoint terms). `DocViewer`, `mount()` and `<office-viewer>` take `locale`
('en' | 'de', default 'en') and `strings`, a partial table merged over the
locale key by key; `StringsProvider` / `useStrings()` give standalone views the
same texts. Numbers and dates in the UI go through Intl with the table's locale;
the English output is unchanged.

This change converts the top bar, the details rows, the common dialogs, the
zoom control, the shared toolbar controls, the source pane and the picture view.
The shared groups (`edit`, `find`, `table`, `format`) are in the table already,
so the document, sheet and slide views can be converted in separate changes.

A unit test checks that every locale has all keys of `en`, no empty text and no
sharp s in German.

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

@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.

markus-kroemer and others added 6 commits November 17, 2026 20:33
…xts from the strings table

The document view's status line, toolbar, context menu, outline, find bar, page setup and header / footer dialogs and the tracked-change tooltips take their texts from the docx, pageSetup and headerFooter groups. The Page 1 of 5 footer preset inserts its text in the UI's language. e2e/locale-docx.spec.ts checks the German texts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s from the strings table

The sheet view's status line, document details, sheet tabs, context menu, find options, print notice and the toolbar (number formats, borders, merge, alignment, rotation, rows, functions, sort, view) take their texts from the xlsx group. Number format previews stay as they are. e2e/locale-xlsx.spec.ts checks the German texts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…heir texts from the strings table

The slide view's toolbar, shape and slide menus, status line and present button, the comments panel and its notices, the File menu, the details dialog, the unsupported-file message and the collaboration chip take their texts from the pptx, comments, file and collab groups. The empty text box placeholder is a data-placeholder attribute shown through attr(), so it follows the locale. e2e/locale.spec.ts checks the German bar, File menu, details dialog and slide view, a partial override and the English default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@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.

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