system-translations

name	system-translations
description	Use when adding localized strings in PHP or HTML, including gettext usage patterns and context-aware translation strings for Zolinga Intl.
argument-hint	<module-name> [string-scope]

Zolinga Translations

Use When

• Adding or changing translatable strings in PHP or HTML.
• Adding context-aware translation keys.

Workflow

1. In PHP, use dgettext('<module-name>', '<string>') (or dngettext(...) for plural forms).
2. Do not create gettext files or locale/ folders manually.
3. In HTML, use gettext attribute and related document translation metadata.
4. For ambiguous single-word labels, prepend context using "\x04" separator (end of transmission character).

Example

dgettext('system-intl', "Confirm form submission\x04Send")

HTML gettext Attribute Formats

For Element Text Content

When the element's text content should be translated:

<h1 gettext="default:.#HASH">Heading Text</h1>
<p gettext="default:.#HASH">Paragraph text</p>

The . means "translate the element's text content". The #HASH is generated by bin/zolinga gettext:extract.

For Attribute Translation (No Direct Content)

When only an attribute should be translated and the element has no direct text content:

<table gettext="default:aria-label#HASH" aria-label="Table description">
<input gettext="default:placeholder#HASH" placeholder="Enter text">

CRITICAL: Do NOT use . when the element has no direct text content unless it has more then one direct child elements. If it has exactly one direct child element, use the child element's gettext attribute instead.

For Multiple Attributes

When translating multiple attributes on the same element:

<div gettext="default:title#HASH1 default:aria-label#HASH2" title="Tooltip" aria-label="Label">

For meta tag content Attribute

When translating the content attribute of a <meta> tag:

<meta name="description" gettext="default:content" content="Description text">
<meta name="page.topic" gettext="default:content" content="Topic text">

Use gettext="default:content" (no hash needed for content attributes on meta tags).

For data-* Attributes

When translating custom data-* attributes:

<div gettext="default:data-providers#HASH default:data-source#HASH" 
     data-providers="Provider list" 
     data-source="Source description">

Common Mistakes to AVOID

WRONG - Element has no direct content but uses .:

<table gettext="default:.#HASH default:aria-label#HASH2" aria-label="...">

CORRECT - Only list attributes when no direct content:

<table gettext="default:aria-label#HASH" aria-label="...">

WRONG - meta tag uses . instead of content:

<meta name="description" gettext="default:." content="...">

CORRECT - meta tag uses content:

<meta name="description" gettext="default:content" content="...">

Workflow for HTML

1. Add gettext attributes with appropriate format (see above)
2. Run bin/zolinga gettext:extract --domains=<domain> to generate/update .po files and add hashes
3. Edit .po files in modules/{module}/locale/ or data/zolinga-intl/default/locale/
4. Run bin/zolinga gettext:compile --all to compile .mo files

Documentation Abstract

• Start with core rendering/runtime docs to understand where translated text is emitted.
• Use content and request processing docs when adding translated HTML output.
• Use global wiki authoring guidance for translation examples in docs.

References

• modules/zolinga-intl/wiki/Zolinga Intl.md — primary translation documentation
• system/wiki/Zolinga Core/Running the System.md
• system/wiki/Zolinga Core/Running the System/Page Request.md
• system/wiki/Zolinga Core/Running the System/Page Request/Processing Page Content.md
• system/wiki/ref/event/system/content.md
• system/wiki/Zolinga Core/WIKI.md