Conversation
Expanded the i18n Architecture section with practical rules for developers and agents: never split sentences across t() calls, always provide context descriptions, use @doist/react-interpolate for inline elements, and run yarn translate after changing translation keys.
WalkthroughThe pull request adds internationalization (i18n) documentation to AGENTS.md. It specifies requirements for a required 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Around line 164-169: Update the documentation and enforcement so they match:
either relax the AGENTS.md wording to say non-empty context descriptions are
"required by convention" or (recommended) add explicit validation in
generate-context.js to fail CI when any context.json entry has an empty
description; implement a check (e.g., in the function that reads/generates
context.json) that iterates entries, detects empty or whitespace-only
descriptions, logs a descriptive error and exits non-zero (process.exit(1)), and
then update AGENTS.md to state that CI will fail on empty descriptions. Include
references to context.json and the generate-context.js validation function so
reviewers can find the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| `yarn translate` is run as part of `yarn workspace @tryghost/i18n test`. In CI, it fails if translation keys or `context.json` are out of date (`failOnUpdate: process.env.CI`). Always run `yarn translate` after adding or changing `t()` calls. | ||
|
|
||
| **Rules for Translation Keys:** | ||
| 1. **Never split sentences across multiple `t()` calls.** Translators cannot reorder words across separate keys. Instead, use `@doist/react-interpolate` to embed React elements (links, bold, etc.) within a single translatable string. | ||
| 2. **Always provide context descriptions.** When adding a new key, add a description in `context.json` explaining where the string appears and what it does. CI will reject empty descriptions. | ||
| 3. **Use interpolation for dynamic values.** Ghost uses `{variable}` syntax: `t('Welcome back, {name}!', {name: firstname})` |
There was a problem hiding this comment.
Clarify CI enforcement wording for empty context descriptions.
The docs state CI rejects empty descriptions, but the referenced enforcement shown in ghost/i18n/generate-context.js only fails when context.json is out of date, not when values are empty. Consider either (a) tightening wording to “required by convention” or (b) adding explicit validation logic for non-empty descriptions and then documenting that behavior.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 164 - 169, Update the documentation and enforcement
so they match: either relax the AGENTS.md wording to say non-empty context
descriptions are "required by convention" or (recommended) add explicit
validation in generate-context.js to fail CI when any context.json entry has an
empty description; implement a check (e.g., in the function that reads/generates
context.json) that iterates entries, detects empty or whitespace-only
descriptions, logs a descriptive error and exits non-zero (process.exit(1)), and
then update AGENTS.md to state that CI will fail on empty descriptions. Include
references to context.json and the generate-context.js validation function so
reviewers can find the change.
2 participants
Summary
yarn translate), CI enforcement, and key rules:t()callscontext.json@doist/react-interpolatefor inline elements (<a>,<strong>, etc.){variable}interpolation for dynamic valuesWhy
Translation contributors flagged that split-sentence keys prevent proper localization. This documentation ensures developers and agents building new features know the rules without needing to discover them through trial and error.
Test plan