Instruction file imported from habakuk007/Gulo-link-in-bio-Wordpress-Plugin (.github/instructions/translation-general.instructions.md). Copyright stays with the author.

WordPress Translation — General Rules

These rules apply to every locale's translation files (.po, .pot, .mo). They complement locale-specific instruction files. Follow the WordPress Polyglots Handbook and consult your locale's style guide for language-specific conventions.

Official Resources

• Polyglots Handbook: https://make.wordpress.org/polyglots/handbook/
• translate.wordpress.org: https://translate.wordpress.org/
• Locale list: https://make.wordpress.org/polyglots/teams/
• General expectations for translators: https://make.wordpress.org/polyglots/handbook/translating/expectations/

Placeholders

• Never translate placeholder tokens — %s, %d, %f, %1$s, %2$d, %(name)s, etc.
• Positional placeholders (%1$s, %2$s) may be reordered to match target-language grammar; update the index numbers accordingly
• Named placeholders (e.g., %(author)s, %(count)d) retain their English key unchanged — only their position in the sentence may change
• Example: "Sent to %s's address" → "An die Adresse von %s gesendet"

HTML in Strings

• Preserve every HTML tag from the source string exactly as-is: <strong>, <a href="...">, <br />, <code>, etc.
• Never add, remove, or modify tags or their attributes
• Translate only the visible text content between the tags
• Replace unnecessary HTML character entities (e.g., ’ for apostrophes, — for em-dashes) with the correct typographic character for the target language; retain entities that are genuinely required (e.g., &, <)

Brand Names & Untranslated Terms

• WordPress is never translated in any locale
• Plugin and theme names are brand names — keep them in their original form
• Product names (WooCommerce, Jetpack, BuddyPress, etc.) are not translated
• Technical API terms with no established translation in a locale stay in English

Plurals

• Always provide all plural forms required by the locale's Plural-Forms PO header — do not hard-code a single form
• English uses 2 forms (1 = singular, other = plural); many locales require 3 or more
• Verify the correct Plural-Forms rule for the locale at https://localization-guide.readthedocs.io/en/latest/l10n/pluralforms.html

Punctuation & Trailing Characters

• Match the trailing punctuation of the source string: if the source ends with ., …, :, or ?, the translation should too — unless the target language has a specific rule against it
• Do not add or remove punctuation that changes sentence structure
• Replace straight quotation marks "..." and '...' with typographic quotes appropriate to the target locale (e.g., „…" for German, «…» for French)

Length & UI Fit

• Do not produce translations significantly longer than the source — UI strings have layout constraints
• When a label must be shorter, rephrase rather than truncate mid-word
• Abbreviate only when the abbreviation is widely understood in the target language and culture

Context & Disambiguation

• Read the surrounding context (comments, file name, msgctxt) before choosing a translation
• Many WordPress strings are context-sensitive: "editor" may mean the text-editing tool or a user role depending on context
• When context is unclear, check the string on a live WordPress installation or ask in the locale's Slack channel

GlotPress Workflow

• All translation suggestions require approval by a General Translation Editor (GTE) or Project Translation Editor (PTE) before they are published
• Do not commit .mo binary files by hand — compile only via composer run make:mo or a GlotPress export
• The canonical source for .po strings is always the .pot file generated by composer run make:pot
• Report translation bugs or glossary gaps in the locale's Slack #polyglots channel or via translate.wordpress.org

File Naming Conventions

WordPress locale codes used in translation file names follow the pattern {text-domain}-{locale}.po:

For a full list of supported locale codes see https://make.wordpress.org/polyglots/teams/.

Compliance Checklist

• All placeholder tokens are preserved and untranslated
• Positional placeholders are reordered correctly for target-language grammar
• All HTML tags are intact and unmodified
• Brand and product names are not translated
• All required plural forms are provided
• Trailing punctuation matches the source string convention
• .mo files are compiled, not hand-edited
• Translation has been submitted via GlotPress and awaits GTE/PTE approval

Source: WordPress Polyglots Handbook · translate.wordpress.org