docs: split i18n guides (router and start) #6363
Conversation
|
Warning Rate limit exceeded@juliomuhlbauer has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 23 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (6)
📝 WalkthroughWalkthroughThis PR reorganizes internationalization (i18n) documentation for React with TanStack Router, creating dedicated guides in both documentation sections and simplifying English locale routing paths in examples. It removes i18n content from the path-params guide and substantially expands the dedicated i18n guide with comprehensive patterns, Paraglide integration, and type-safety examples. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
| Command | Status | Duration | Result |
|---|---|---|---|
nx affected --targets=test:eslint,test:unit,tes... |
❌ Failed | 1m 11s | View ↗ |
nx run-many --target=build --exclude=examples/*... |
✅ Succeeded | 1s | View ↗ |
☁️ Nx Cloud last updated this comment at 2026-01-11 17:53:07 UTC
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Fix all issues with AI agents
In @docs/router/config.json:
- Line 330: The "to" path value contains a typo: change the string
"framework/react/guide/Internationalization-18n" to
"framework/react/guide/Internationalization-i18n" so the navigation link
resolves correctly; update the "to" field where that exact value appears in the
config JSON.
In @docs/start/config.json:
- Line 182: The link target string
"framework/react/guide/Internationalization-i18n" has a capitalization mismatch
with the actual file name; update the config entry to use the lowercase path
"framework/react/guide/internationalization-i18n" so the route matches the
actual filename (adjust the value for the key that currently contains "to":
"framework/react/guide/Internationalization-i18n").
In @docs/start/framework/react/guide/internationalization-i18n.md:
- Around line 47-49: Correct the typo in the documentation heading by changing
"Set the lang atribute in html" to "Set the lang attribute in html" (refers to
the instruction about setting lang in __root.tsx); update the phrase wherever
present in this markdown to replace "atribute" with "attribute".
In @examples/react/i18n-paraglide/README.md:
- Line 47: The README sentence "If you use TanStack Start and do not need
offline capabilities, you don`t need to use the shouldRedirect logic, only
paraglideMiddleware in the TanStack Start Paraglide integration guide." has a
backtick in "don`t" — replace the backtick with a proper apostrophe so it reads
"don't"; update that line in examples/react/i18n-paraglide/README.md where the
sentence appears.
In @examples/react/start-i18n-paraglide/README.md:
- Around line 124-126: Fix the typo in the README sentence: change "Set the lang
atribute in html at __root.tsx:" to "Set the lang attribute in html at
__root.tsx:" so "atribute" is corrected to "attribute" in the HTML Language
Attribute section.
- Line 112: The heading "#### Server Middleware (SSR)" violates the markdown
heading sequence after the "## Type-safe Translated Pathnames" section; change
"#### Server Middleware (SSR)" to "### Server Middleware (SSR)" to restore
proper h2→h3 progression, or alternatively change the subsections under
"Type-safe Translated Pathnames" to be h3 so the current h4 becomes valid—update
the heading text "Server Middleware (SSR)" accordingly in the README.
🧹 Nitpick comments (2)
examples/react/i18n-paraglide/README.md (1)
100-109: Consider adding a comment about the locale order.The examples show English and Spanish locales, but the order might not be obvious to readers. It would be helpful to clarify which locale is the base locale and how the order affects the routing behavior, especially since the vite config changes in this PR remove the
/enprefix.docs/start/framework/react/guide/internationalization-i18n.md (1)
18-18: Verify link format for internal documentation references.Lines 18 and 33 use absolute URLs to tanstack.com. Per the coding guidelines, internal documentation references should use relative links to the
docs/folder format (e.g.,./guide/data-loading). Verify if these should be converted to relative links pointing to the companion i18n guide in the router documentation.Also applies to: 33-33
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
docs/router/config.jsondocs/router/framework/react/guide/internationalization-i18n.mddocs/router/framework/react/guide/path-params.mddocs/start/config.jsondocs/start/framework/react/guide/internationalization-i18n.mde2e/react-start/i18n-paraglide/vite.config.tsexamples/react/i18n-paraglide/README.mdexamples/react/start-i18n-paraglide/README.mdexamples/react/start-i18n-paraglide/vite.config.ts
💤 Files with no reviewable changes (1)
- docs/router/framework/react/guide/path-params.md
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Use TypeScript strict mode with extensive type safety for all code
Files:
examples/react/start-i18n-paraglide/vite.config.tse2e/react-start/i18n-paraglide/vite.config.ts
**/*.{js,ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
Implement ESLint rules for router best practices using the ESLint plugin router
Files:
examples/react/start-i18n-paraglide/vite.config.tse2e/react-start/i18n-paraglide/vite.config.ts
docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Use relative links to
docs/folder format (e.g.,./guide/data-loading) for internal documentation references
Files:
docs/start/framework/react/guide/internationalization-i18n.mddocs/router/framework/react/guide/internationalization-i18n.md
🧠 Learnings (9)
📓 Common learnings
Learnt from: schiller-manuel
Repo: TanStack/router PR: 6211
File: e2e/react-start/i18n-paraglide/src/server.ts:6-6
Timestamp: 2025-12-24T22:47:44.320Z
Learning: In TanStack Router projects using `inlang/paraglide-js`, the callback passed to `paraglideMiddleware` should use `() => handler.fetch(req)` (referencing the outer `req`) instead of `({ request }) => handler.fetch(request)`. This is intentional because the router needs the untouched URL to perform its own rewrite logic with `deLocalizeUrl`/`localizeUrl`. The middleware's processed request would delocalize the URL and interfere with the router's rewrite handling.
Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-06T15:03:07.223Z
Learning: Applies to **/*.{js,ts,tsx} : Implement ESLint rules for router best practices using the ESLint plugin router
📚 Learning: 2025-12-24T22:47:44.320Z
Learnt from: schiller-manuel
Repo: TanStack/router PR: 6211
File: e2e/react-start/i18n-paraglide/src/server.ts:6-6
Timestamp: 2025-12-24T22:47:44.320Z
Learning: In TanStack Router projects using `inlang/paraglide-js`, the callback passed to `paraglideMiddleware` should use `() => handler.fetch(req)` (referencing the outer `req`) instead of `({ request }) => handler.fetch(request)`. This is intentional because the router needs the untouched URL to perform its own rewrite logic with `deLocalizeUrl`/`localizeUrl`. The middleware's processed request would delocalize the URL and interfere with the router's rewrite handling.
Applied to files:
examples/react/i18n-paraglide/README.mdexamples/react/start-i18n-paraglide/README.mddocs/router/framework/react/guide/internationalization-i18n.md
📚 Learning: 2025-12-21T12:52:35.231Z
Learnt from: Sheraff
Repo: TanStack/router PR: 6171
File: packages/router-core/src/new-process-route-tree.ts:898-898
Timestamp: 2025-12-21T12:52:35.231Z
Learning: In `packages/router-core/src/new-process-route-tree.ts`, the matching logic intentionally allows paths without trailing slashes to match index routes with trailing slashes (e.g., `/a` can match `/a/` route), but not vice-versa (e.g., `/a/` cannot match `/a` layout route). This is implemented via the condition `!pathIsIndex || node.kind === SEGMENT_TYPE_INDEX` and is a deliberate design decision to provide better UX by being permissive with missing trailing slashes.
Applied to files:
examples/react/i18n-paraglide/README.mdexamples/react/start-i18n-paraglide/README.mddocs/router/framework/react/guide/internationalization-i18n.md
📚 Learning: 2025-09-28T21:41:45.233Z
Learnt from: nlynzaad
Repo: TanStack/router PR: 5284
File: e2e/react-start/basic/server.js:50-0
Timestamp: 2025-09-28T21:41:45.233Z
Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.
Applied to files:
examples/react/i18n-paraglide/README.mdexamples/react/start-i18n-paraglide/README.md
📚 Learning: 2025-10-14T18:59:33.990Z
Learnt from: FatahChan
Repo: TanStack/router PR: 5475
File: e2e/react-start/basic-prerendering/src/routes/redirect/$target/via-beforeLoad.tsx:8-0
Timestamp: 2025-10-14T18:59:33.990Z
Learning: In TanStack Router e2e test files, when a route parameter is validated at the route level (e.g., using zod in validateSearch or param validation), switch statements on that parameter do not require a default case, as the validation ensures only expected values will reach the switch.
Applied to files:
docs/router/framework/react/guide/internationalization-i18n.md
📚 Learning: 2025-09-22T00:56:53.426Z
Learnt from: nlynzaad
Repo: TanStack/router PR: 5182
File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
Timestamp: 2025-09-22T00:56:53.426Z
Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.
Applied to files:
docs/router/framework/react/guide/internationalization-i18n.md
📚 Learning: 2025-12-06T15:03:07.223Z
Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-06T15:03:07.223Z
Learning: Applies to **/*.{js,ts,tsx} : Implement ESLint rules for router best practices using the ESLint plugin router
Applied to files:
docs/router/framework/react/guide/internationalization-i18n.md
📚 Learning: 2025-12-06T15:03:07.223Z
Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-06T15:03:07.223Z
Learning: Implement type-safe routing with search params and path params
Applied to files:
docs/router/framework/react/guide/internationalization-i18n.md
📚 Learning: 2025-10-01T18:30:26.591Z
Learnt from: schiller-manuel
Repo: TanStack/router PR: 5330
File: packages/router-core/src/router.ts:2231-2245
Timestamp: 2025-10-01T18:30:26.591Z
Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.
Applied to files:
docs/router/framework/react/guide/internationalization-i18n.md
🪛 LanguageTool
docs/start/framework/react/guide/internationalization-i18n.md
[style] ~47-~47: This phrase is redundant (‘L’ stands for ‘language’). Use simply “HTML”.
Context: ...=> handler.fetch(req)) }, } ``` #### HTML Language Attribute Set the lang atribute in htm...
(ACRONYM_TAUTOLOGY)
[grammar] ~49-~49: Ensure spelling is correct
Context: ...# HTML Language Attribute Set the lang atribute in html at __root.tsx: ```tsx import...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
examples/react/start-i18n-paraglide/README.md
[style] ~124-~124: This phrase is redundant (‘L’ stands for ‘language’). Use simply “HTML”.
Context: ...=> handler.fetch(req)) }, } ``` #### HTML Language Attribute Set the lang atribute in htm...
(ACRONYM_TAUTOLOGY)
[grammar] ~126-~126: Ensure spelling is correct
Context: ...# HTML Language Attribute Set the lang atribute in html at __root.tsx: ```tsx import...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/router/framework/react/guide/internationalization-i18n.md
[grammar] ~147-~147: Use a hyphen to join words.
Context: ... also create more sophisticated language switching logic: ```tsx function Advanc...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
examples/react/start-i18n-paraglide/README.md
112-112: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
🔇 Additional comments (6)
e2e/react-start/i18n-paraglide/vite.config.ts (1)
20-20: LGTM! English locale now uses root paths without prefix.The changes simplify English URL paths by removing the
/enprefix, making English the default/base locale. This is a common i18n pattern where the primary locale is served without a prefix while other locales (like German at/de) retain their prefix.Also applies to: 27-27, 34-34
examples/react/i18n-paraglide/README.md (1)
54-55: Verify the import path is correct.The import uses
@reland/i18n/runtimewhich doesn't match the Paraglide setup shown earlier in the document (which uses./paraglide/runtime). This might be example code from a different project or could be a mistake.Should this import be
./paraglide/runtimeto match the setup in lines 23 and 37, or is@reland/i18n/runtimean intentional path alias/package reference?examples/react/start-i18n-paraglide/vite.config.ts (1)
20-20: LGTM! Consistent with e2e configuration.The URL localization changes match the updates in
e2e/react-start/i18n-paraglide/vite.config.ts, establishing a consistent pattern where English serves as the default locale without a URL prefix while German retains the/deprefix.Also applies to: 27-27, 34-34
examples/react/start-i18n-paraglide/README.md (1)
39-39: Verify the@reland/i18n/runtimeimport.The code imports from
@reland/i18n/runtime, which doesn't appear to be a valid package in the TanStack ecosystem. This import statement appears in multiple places (lines 39, 402, 440 in File 3). Verify if this should reference Paraglide's locale utilities instead or if it's a placeholder that needs to be corrected.🤔 What should this import be?
Based on the Paraglide integration context, this might need to be:
- A custom locale type definition
- An import from
@inlang/paraglide-jsor similar- Or left as-is if it's a custom application module
Please verify and update if necessary.
Also applies to: 402-402, 440-440
docs/router/framework/react/guide/internationalization-i18n.md (2)
402-402: Verify the@reland/i18n/runtimeimport.The code imports from
@reland/i18n/runtime(lines 402, 448-456), which doesn't appear to be a valid package. This same import issue appears in File 2 as well. Verify if this should reference a custom locale type, Paraglide's utilities, or another source. Ensure the import is updated to match your actual i18n library setup.Also applies to: 448-456
147-147: Minor grammar note: Consider hyphenation in "language switching".Static analysis suggests "language switching" could be hyphenated as "language-switching" in certain contexts. However, this is a stylistic choice and not critical. The current usage is acceptable in documentation.
| - Compiler feedback for routing mistakes | ||
| You can use the `localizeHref` function to map the routes to localized versions and import into the pages option in the TanStack Start plugin. For this to work you will need to compile paraglide before the build with the CLI. | ||
| #### Server Middleware (SSR) |
There was a problem hiding this comment.
Fix markdown heading level structure.
Line 112 starts a section with #### Server Middleware (SSR), but this violates the markdown heading increment rule (MD001). The preceding section "## Type-safe Translated Pathnames" is at h2, so the next heading should be h3, not h4. This creates a gap in the heading hierarchy.
📝 Proposed fix
-#### Server Middleware (SSR)
+### Server Middleware (SSR)Alternatively, restructure the "Type-safe Translated Pathnames" section to use h3 headings for its subsections.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| #### Server Middleware (SSR) | |
| ### Server Middleware (SSR) |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
112-112: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @examples/react/start-i18n-paraglide/README.md at line 112, The heading "####
Server Middleware (SSR)" violates the markdown heading sequence after the "##
Type-safe Translated Pathnames" section; change "#### Server Middleware (SSR)"
to "### Server Middleware (SSR)" to restore proper h2→h3 progression, or
alternatively change the subsections under "Type-safe Translated Pathnames" to
be h3 so the current h4 becomes valid—update the heading text "Server Middleware
(SSR)" accordingly in the README.
1 participant
Summary by CodeRabbit
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.