Skip to content

docs: internationalization (i18n) - #238

Open
marcelo-maciel wants to merge 4 commits into
fullstackhero:mainfrom
marcelo-maciel:docs/i18n
Open

docs: internationalization (i18n)#238
marcelo-maciel wants to merge 4 commits into
fullstackhero:mainfrom
marcelo-maciel:docs/i18n

Conversation

@marcelo-maciel

@marcelo-maciel marcelo-maciel commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Documents the internationalization (i18n) feature and adds the changelog entry.

The code PR this originally tracked, fullstackhero/dotnet-starter-kit#1344, was split into four on review request. This documentation covers all four, so it stays a single PR: internationalization.mdx is one page whose sections map across the split, and cutting it into four would put four PRs on the same file and leave three of them describing half a feature.

Section here Code slice
Request localization, culture resolution chain, per-user language, Configuration fullstackhero/dotnet-starter-kit#1360 (framework)
code on ProblemDetails in error-handling.mdx fullstackhero/dotnet-starter-kit#1360 (framework)
String resources — the per-module {Module}Resources catalogs, localized messages fullstackhero/dotnet-starter-kit#1361 (modules)
Frontend (admin and dashboard) — catalogs, detection and normalization, Accept-Language, switcher, locale-aware formatting fullstackhero/dotnet-starter-kit#1362 and fullstackhero/dotnet-starter-kit#1363
Adding a language, Gotchas, changelog entry spans all four

Please merge this after the last of the four, not with the first. Landing it alongside the framework slice alone would publish the module-catalog and front-end sections before that code is on main, and a reader following those instructions would find nothing there. Docs lagging the code by a few merges is the safer direction (Golden Rule #10 is satisfied by the docs travelling with the change, and all four are in flight together).

  • New cross-cutting concerns page covering the request culture resolution chain, resource catalogs (SharedResources plus per-module {Module}Resources), localized ProblemDetails and FluentValidation messages, the User.Locale field and fallback, and the front-end react-i18next setup with enforced en-US / pt-BR key parity.
  • Links the new page from the cross-cutting concerns index.
  • Documents the stable code extension on ProblemDetails in the error-handling page, and corrects pre-existing drift in that table: it said title was the exception type name, which post-i18n is the localized title by status, with the type name only as fallback.
  • Adds a changelog entry for the feature.

Add a cross-cutting-concerns page covering end-to-end localization:
backend IStringLocalizer with neutral-culture resx and RequestLocalization,
the five-step culture-resolution chain, per-user User.Locale on the JWT
locale claim, and both React apps on react-i18next with a language switcher.
Includes an "adding a language" guide and a changelog entry.
@iammukeshm

Copy link
Copy Markdown
Member

Reviewed - thorough page, and the culture-resolution chain + neutral-resx-name gotchas are exactly the right level of detail. Holding until upstream #1344 merges (still open). When it does: rebase over main's em-dash -> hyphen conversion, re-date the changelog section to the actual merge date, and double-check the final shipped config keys (LocalizationOptions:DefaultCulture, SupportedCultures, defaultLanguage) against the merged code before we publish.

Localized problem details mean `detail` is prose in the caller's language, so
clients must branch on the exception's MessageKey, now emitted as a `code`
extension. Documents the field in Error handling, cross-links it from
Internationalization, and extends the i18n changelog entry.

Also corrects the CustomException row: `title` is the localized status title,
not the exception type name (the type name is only the fallback).
@marcelo-maciel

Copy link
Copy Markdown
Contributor Author

Rebased onto main; this is MERGEABLE again at 3f57a842. astro check is clean: 0 errors, 0 warnings.

The conflict was cross-cutting-concerns/index.mdx, where main's em dash sweep (a96478cf) met this branch's "eleven concerns" to "twelve concerns" edit. Resolved by keeping this branch's content with main's punctuation, and the remaining 24 em dashes in the new i18n content were converted too, so the site stays at zero.

One consequence of that sweep worth naming, because it is silent. Converting to - changes the heading slug: github-slugger turns code — the machine-readable discriminator into code--the-machine-readable-discriminator, but code - the machine-readable discriminator into code---the-machine-readable-discriminator, with three hyphens. The two links into that section from internationalization.mdx and the changelog were still on the two-hyphen form and are retargeted in 3f57a842. Verified by running the site's own github-slugger and reproducing the old anchor first, so the method is checked rather than assumed. npm run build could not be used for this: it fails in buildEnd fetching JetBrains Mono from fonts.gstatic.com on an untouched main too, and dies before writing any HTML.

Pre-existing on main, not from this PR, but the same failure mode: frontend/architecture.mdx:221 links to /docs/frontend/dashboard/#chat--the-realtime-showcase, while the heading is now ## Chat - the realtime showcase, whose slug is chat---the-realtime-showcase. That link is broken on the live site. Left alone here to keep this PR scoped; happy to send it as a one-line PR if you want.

On scope: this PR stays whole and covers all four slices of the code split (fullstackhero/dotnet-starter-kit#1360, #1361, #1362, #1363) - internationalization.mdx is one page whose sections map across them. It should merge after the last of the four, so the page never documents code that is not on main yet.

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.

2 participants