Skip to content

Add translator documentation for all en.yml strings - #447

Open
siebrand wants to merge 1 commit into
OpenHistoricalMap:stagingfrom
siebrand:staging
Open

Add translator documentation for all en.yml strings#447
siebrand wants to merge 1 commit into
OpenHistoricalMap:stagingfrom
siebrand:staging

Conversation

@siebrand

Copy link
Copy Markdown

Complete config/locales/qqq.yml with descriptions for all 3,074 translatable strings, covering context, variable placeholders, and usage notes to assist translators.

Description

qqq.yml is a special TranslateWiki file that provides documentation hints for translators. It is not a translation itself and is not managed by TranslateWiki — it lives in the source repo and is read by TranslateWiki to show context to translators working on any of the supported languages.

Previously the file was largely incomplete. This PR adds descriptions for all 3,074 translatable strings in en.yml, covering:

  • Where and how each string appears in the UI
  • Variable placeholders (%{name}, {{name}}) with explanations of what each contains
  • Strings that should not be translated (e.g. language names, proper nouns)

How has this been tested?

Verified with a Ruby script that all 3,074 en.yml leaf keys have a corresponding qqq.yml entry:

EN leaf keys: 3074
QQQ leaf keys: 3239
Missing: 0

The higher QQQ count reflects plural form documentation entries (one/other/few etc.) that are documented separately.

@github-actions

Copy link
Copy Markdown
2 Warnings
⚠️ Number of updated lines of code is too large to be in one PR. Perhaps it should be separated into two or more?
⚠️ The following YAML files other than en.yml have been modified: config/locales/qqq.yml. Only en.yml is allowed to be changed. Translations are updated via Translatewiki, see CONTRIBUTING.md.

Generated by 🚫 Danger

Complete config/locales/qqq.yml with descriptions for all 3,074
translatable strings, covering context, variable placeholders, and
usage notes to assist translators.

Co-authored-by: Amazon Q Developer <amazon-q-developer@amazon.com>
@1ec5

1ec5 commented Aug 12, 2026

Copy link
Copy Markdown
Member

Thanks for looking into this. Do you know why the upstream openstreetmap-website project doesn’t have a qqq.yml? Is that just an oversight, or should we be excluding it from both projects? I think openstreetmap-website has historically assumed that they could use comments in en.yml to communicate nuances to translators in some cases, but obviously /qqq is a more robust mechanism for that.

The departure from openstreetmap-website is significant because we’re also considering redoing this fork to rely on an override file instead of repeating the entire base localization: OpenHistoricalMap/issues#735 (comment). In that case, we would maintain a separate qqq.yml in the same directory as our override files, coexisting with any qqq.yml copied over from upstream (but that file doesn’t exist yet).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants