Add translator tooling docs, plural examples, and tests#262
Merged
Conversation
… and tests This adds comprehensive translator documentation covering message keys, variable usage, plural forms, and adding new locales. It includes plural form example messages in en-US and es-ES locales demonstrating Fluent's CLDR plural syntax and limitations due to the current API passing arguments as strings. Key constants for the examples are added to src/localization/keys.rs with compile-time audit support. Unit tests are introduced to verify plural message resolution and variable interpolation for English and Spanish locales. The user guide is updated to reference the new translator guide, and the roadmap marks item 3.7.3 done, fulfilling the goal of providing tooling and documentation for translators. No new dependencies are introduced; quality gates for formatting, linting, and testing pass successfully. Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
Contributor
Summary by CodeRabbitRelease Notes
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughIntroduce translator tooling and localisation documentation for ExecPlan 3.7.3. Add a translators guide, example plural messages for Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Poem
🚥 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)
Comment |
Contributor
Reviewer's GuideAdds a comprehensive translator guide and exec plan for Netsuke localization, introduces example pluralized messages in English and Spanish with corresponding localization keys, and extends localization tests and user/roadmap docs to validate plural interpolation and mark translator tooling work as complete. Sequence diagram for example plural message rendering and fallbacksequenceDiagram
actor Test as LocalizationTests
participant LM as LocalizedMessage
participant FL as FluentLocalizer
participant FE as FluentEngine
Test->>LM: new(EXAMPLE_FILES_PROCESSED)
Test->>LM: with_arg("count", 1)
LM->>LM: convert 1 to String
LM->>FL: resolve(key, args_as_strings)
FL->>FE: format_pattern(key, args_as_strings)
FE-->>FL: select default_other_variant
FL-->>LM: "Processed 1 files." (other variant)
LM-->>Test: formatted_message
note over Test,FE: Tests assert interpolation works
note over Test,FE: but plural selection uses other variant due to string args
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 3 issues, and left some high level feedback:
- In the translator guide, the CLDR plural categories table lists French as having
one,many,other, but CLDR defines onlyoneandotherfor French—updating this to match CLDR would avoid confusing translators. - The plural examples for
example.errors_foundin the ExecPlan and translator guide use the[0]selector, while the actual FTL files use[zero]; consider aligning the examples with the implemented[zero]form so documentation and source stay consistent.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the translator guide, the CLDR plural categories table lists French as having `one`, `many`, `other`, but CLDR defines only `one` and `other` for French—updating this to match CLDR would avoid confusing translators.
- The plural examples for `example.errors_found` in the ExecPlan and translator guide use the `[0]` selector, while the actual FTL files use `[zero]`; consider aligning the examples with the implemented `[zero]` form so documentation and source stay consistent.
## Individual Comments
### Comment 1
<location> `docs/translators-guide.md:187` </location>
<code_context>
+| -------- | ---------- |
+| English | `one`, `other` |
+| Spanish | `one`, `other` |
+| French | `one`, `many`, `other` |
+| Russian | `one`, `few`, `many`, `other` |
+| Arabic | `zero`, `one`, `two`, `few`, `many`, `other` |
</code_context>
<issue_to_address>
**issue:** French CLDR plural categories are misstated; CLDR defines `one` and `other` (no `many`).
Please update the French row to list only `one` and `other` so it matches the CLDR plural rules and avoids confusing translators.
</issue_to_address>
### Comment 2
<location> `docs/translators-guide.md:142` </location>
<code_context>
+
+## 5. Plural Forms
+
+Fluent uses CLDR plural rules to handle grammatical number. Different languages
+have different plural categories.
+
</code_context>
<issue_to_address>
**suggestion (review_instructions):** "CLDR" is introduced here without being defined; it should be expanded on first use.
Consider updating this sentence to something like "Fluent uses Common Locale Data Repository (CLDR) plural rules" so that the acronym is defined when first introduced. Later uses can remain as CLDR.
<details>
<summary>Review instructions:</summary>
**Path patterns:** `**/*.md`
**Instructions:**
Define uncommon acronyms on first use.
</details>
</issue_to_address>
### Comment 3
<location> `docs/translators-guide.md:192` </location>
<code_context>
+| Arabic | `zero`, `one`, `two`, `few`, `many`, `other` |
+| Japanese | `other` (no grammatical plural) |
+
+Consult the [CLDR plural rules][cldr-plural] for your target language.
+
+[cldr-plural]: https://cldr.unicode.org/index/cldr-spec/plural-rules
</code_context>
<issue_to_address>
**suggestion (review_instructions):** This sentence uses the second-person pronoun "your", which the style guide prohibits.
To avoid second-person pronouns, rephrase this line in an impersonal form, for example: "Consult the [CLDR plural rules][cldr-plural] for the target language."
<details>
<summary>Review instructions:</summary>
**Path patterns:** `**/*.md`
**Instructions:**
Avoid 2nd person or 1st person pronouns ("I", "you", "we").
</details>
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ac967d6ae3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 13
🤖 Fix all issues with AI agents
In `@docs/execplans/3-7-3-translator-tooling-and-documentation.md`:
- Line 163: Update the phrase in the documentation heading that currently reads
"FTL file structure - Location, section organisation, comments" to use
en-US/oxendict spelling by replacing "organisation" with "organization"; locate
the exact heading text in the translator tooling doc and make the single-word
substitution so the line reads "FTL file structure - Location, section
organization, comments".
- Line 172: Replace the British spelling "pluralisation" with the required
"-ize" form "pluralization" in the line containing the phrase "Add demonstration
messages showing pluralisation:" so the sentence reads "Add demonstration
messages showing pluralization:"; update any other occurrences of
"pluralisation" in this document (search for the exact token) to "pluralization"
to comply with the en-GB-oxendict spelling rule.
- Line 67: The doc contains the British spelling "synchronised" which must be
changed to the required -ize form; locate the occurrence of "synchronised" in
the text (the sentence "are not synchronised across all locales. Severity: low.
Likelihood: medium."), replace it with "synchronized", and scan the same
document for other -ise endings (e.g., "synchronise", "organise") and convert
them to the -ize variants to comply with the documentation spelling guideline.
- Line 145: Replace the British spelling "organised" with the American "-ize"
form "organized" in the sentence containing "`stdlib.fetch.url_invalid`)
organised by domain:"; update the text so it reads "`stdlib.fetch.url_invalid`)
organized by domain:" ensuring the only change is the spelling of "organised" to
"organized".
In `@docs/roadmap.md`:
- Around line 237-239: Update roadmap item 3.7.3 to define measurable outcomes
instead of intentions: replace the current bullet "Provide translator tooling
and documentation" and its sub-bullets with the proposed wording that states
deliverables and acceptance criteria (e.g., "Publish translator tooling
documentation with verified examples", sub-bullets "Document message keys,
plural categories, and variable usage with worked FTL samples" and "Add smoke
tests covering en-US plus one secondary locale (es-ES)") so the task and
completion criteria are explicit and testable.
In `@docs/translators-guide.md`:
- Around line 192-193: Replace the second-person wording in the sentence
"Consult the [CLDR plural rules][cldr-plural] for your target language." with a
neutral phrasing: change "your target language" to "the target language" so the
line reads "Consult the [CLDR plural rules][cldr-plural] for the target
language." This removes second-person pronouns to comply with the documentation
style guidelines.
- Around line 8-10: Replace reference-style Markdown links with inline links for
the "Project Fluent" and "CLDR plural rules" references: locate the occurrences
of "[Project Fluent][fluent]" and "[CLDR plural rules][cldr-plural]" in
docs/translators-guide.md and change them to inline form
"(https://projectfluent.org/)" and
"(https://cldr.unicode.org/index/cldr-spec/plural-rules)" respectively, then
remove the corresponding reference definitions "[fluent]: ..." and
"[cldr-plural]: ..." (also apply the same replacement to the other occurrences
mentioned at the comment locations such as lines ~25 and ~192-194).
- Around line 1-7: Change all markdown headings in the translators-guide
document from title case to sentence case; find headings like "Netsuke
Translator Guide", "File Structure", "Message Key Conventions" (and any other
level-1/2/3 headings including those in the block around the previously noted
section) and update them to sentence case (e.g., "Netsuke translator guide",
"File structure", "Message key conventions") consistently across the file;
ensure you only alter the heading text casing and preserve hashes, links, and
surrounding content.
- Around line 63-64: Replace the British spelling "organised" with the OED -ize
variant "organized" in the sentence "Netsuke uses hierarchical dot-notation for
message keys, organised by domain:" so it reads "Netsuke uses hierarchical
dot-notation for message keys, organized by domain:"; update that exact string
in docs/translators-guide.md (the line containing the sentence) to conform to
en-GB-oxendict -ize spelling.
- Around line 65-76: Add a short caption line immediately above each table and
diagram in the translators-guide.md; for the shown table (the one starting with
the header "| Domain | Purpose | Example |" and listing domains like `cli.*`,
`clap-error-*`, `runner.*`, `manifest.*`, `ir.*`, `ninja_gen.*`, `stdlib.*`,
`host_pattern.*`, `network_policy.*`, `example.*`) insert a caption such as
"Table: Message key domains and examples." Do the same for the other tables
referenced (the blocks around the ranges you noted) and for any diagrams—ensure
each caption is a single plain-text line starting with "Table:" or "Figure:" as
appropriate and placed directly above the table/diagram so it meets the
documentation requirement.
In `@locales/en-US/messages.ftl`:
- Around line 329-333: The plural selector for example.errors_found uses the
non-CLDR key [zero]; update the selector to the numeric form [0] so the zero
case will match for $count, i.e., in the message pattern for
example.errors_found replace the [zero] selector with [0] and keep the existing
[one] and [other] branches intact.
In `@locales/es-ES/messages.ftl`:
- Around line 330-334: The plural variants in the message key
example.errors_found use an invalid CLDR category [zero]; replace the [zero]
variant with a numeric selector [0] so zero is matched explicitly for $count,
keeping the existing [one] and [other] branches intact; update the selector in
the example.errors_found pattern to use [0] instead of [zero].
In `@tests/localization_tests.rs`:
- Around line 39-123: The tests repeat the same lock/localizer/guard setup; add
an rstest fixture named localiser_guards that accepts a locale: &str and returns
the acquired MutexGuard and LocalizerGuard by calling localizer_test_lock(),
cli_localization::build_localizer(Some(locale)), and
localization::set_localizer_for_tests(Arc::from(...)); then update the test
functions example_files_processed_message_resolves,
example_errors_found_message_resolves, and
variable_interpolation_works_correctly to take the fixture (e.g.,
localiser_guards: Result<(MutexGuard<'static, ()>, LocalizerGuard)>) or
destructured guards as an argument and remove the duplicated calls to
localizer_test_lock, cli_localization::build_localizer, and
localization::set_localizer_for_tests.
…zation tests - Add `docs/translators-guide.md` with detailed instructions on Fluent syntax, message key conventions, variable usage, plural forms, and locale addition. - Add plural form examples to `en-US` and `es-ES` locales with matching key constants. - Enhance localization smoke tests to verify message resolution for `en-US` and `es-ES`. - Update roadmap to reflect completed translator tooling and documentation. - Fix minor typos and wording for consistency and clarity in localization docs. Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@docs/execplans/3-7-3-translator-tooling-and-documentation.md`:
- Around line 107-111: Edit the sentence starting "Keep plural form examples as
documentation despite selection not working." in the docs/execplans file and
insert a comma after "documentation" so it reads "Keep plural form examples as
documentation, despite selection not working." — update the block containing
that Decision paragraph (the lines with "Decision: Keep plural form examples as
documentation despite selection not working.") to include the comma.
In `@docs/translators-guide.md`:
- Around line 63-77: Replace the invisible HTML comment "<!-- Table 1: Message
key domains and their purposes -->" with a visible plain-text caption line
(e.g., "Table 1: Message key domains and their purposes") immediately above the
table that begins with the header "| Domain | Purpose | Example |"; do the same
for the other two tables that currently use HTML comments (the other "<!-- Table
... -->" comment blocks) so captions render in the Markdown output.
…kdown - Corrected punctuation for clarity in execplans documentation. - Replaced HTML comment tags with markdown text in translators-guide.md for better rendering of table captions. - Improved overall readability of documentation files. Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In `@docs/execplans/3-7-3-translator-tooling-and-documentation.md`:
- Around line 13-16: Update the prose in Roadmap item 3.7.3 to use en-GB
spelling by replacing US "localization" with en-GB "localisation" throughout the
narrative text (e.g., the paragraph starting "Roadmap item 3.7.3 requires...")
and in the other noted prose blocks (around the referenced ranges), while
leaving any identifiers, file names, or external API names that intentionally
use US spelling unchanged; ensure the documentation follows en-GB-oxendict
conventions for spelling and grammar.
- Around line 31-36: Update the success criteria bullet that currently reads
"FTL files containing working plural form examples" to explicitly reflect the
documented plural-selection limitation: replace that phrase with something like
"FTL files containing plural examples demonstrating that missing plural forms
resolve to the default [other] form" and ensure the wording aligns with the
translator guide and unit tests for plural rendering (en-US and es-ES).
In `@docs/translators-guide.md`:
- Around line 201-203: Update the paragraph that starts with "The netsuke
localization API currently passes all arguments..." by replacing the lowercase
product name "netsuke" with the correctly capitalized "Netsuke" so the sentence
reads "The Netsuke localization API..." (search for the exact phrase "The
netsuke localization API" to locate the paragraph).
- Around line 8-10: The document uses US spelling "localization" in narrative
text; update these narrative occurrences to British en-GB spelling
"localisation" (following en-GB-oxendict, e.g., “-our”) while leaving any
identifiers, filenames, or external API references that intentionally use US
spelling unchanged; search for the token "localization" in narrative paragraphs
(including the initial paragraph mentioning Project Fluent and the other cited
sections) and replace with "localisation", keeping contextual grammar intact and
not altering code/identifier blocks or links.
- Around line 80-82: Reflow the paragraph that mentions src/localization/keys.rs
and the example constant CLI_FLAG_FILE_HELP so no line exceeds 80 characters;
break the sentence into multiple lines at sensible word boundaries (e.g., after
"defined in `src/localization/keys.rs`" and before/after the example) while
preserving the exact text and inline code fragments (`UPPER_SNAKE_CASE`,
`CLI_FLAG_FILE_HELP`, `cli.flag.file.help`).
- Updated translator tooling and documentation to note that FTL plural form examples default to `[other]` variant due to string argument passing. - Clarified unit tests validate message resolution and variable interpolation in both en-US and es-ES. - Revised translators guide to improve formatting and corrected capitalization of "Netsuke". - Added explanation of current limitation where the localization API passes arguments as strings rather than numeric types, affecting CLDR plural selector matching. Co-authored-by: devboxerhub[bot] <devboxerhub[bot]@users.noreply.github.com>
Owner
Author
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/translators-guide.md`:
- Around line 197-198: Reflow the paragraph containing the CLDR link so no line
exceeds 80 characters while preserving the inline Markdown link; specifically
edit the sentence "Consult the [CLDR plural
rules](https://cldr.unicode.org/index/cldr-spec/plural-rules) for the target
language." into multiple wrapped lines (max 80 cols) or short clauses that keep
the [CLDR plural rules](https://cldr.unicode.org/index/cldr-spec/plural-rules)
link intact and on the same Markdown line as its text.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Changes
Documentation
Localization data
Code
Tests
Review & QA
Validation and test plan
Artefacts
Rationale
Notes for reviewers
◳ Generated by DevBoxer ◰
ℹ️ Tag @devboxerhub to ask questions and address PR feedback
📎 Task: https://www.devboxer.com/task/d6b30e20-e037-407a-b761-6c1769fcd2b1
Summary by Sourcery
Document translator workflows and pluralization patterns, add example plural messages to English and Spanish locales, and validate them with new localization tests while marking the corresponding roadmap item complete.
New Features:
Enhancements:
Documentation:
Tests: