菜单
Use when writing HTML that needs static translation via gettext attributes. Covers the gettext attribute syntax, gettext-context, nested element translation, meta tag, and translation modes.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when writing PHP code that needs localized strings. Covers dgettext, dngettext, context separator, enum label convention, and static analysis constraints.
Use when creating or modifying translated Zolinga web components. Covers importing web-component-intl.js, locale-aware template loading, and gettext in component HTML/JS.
Use when asked to localize a module, add translations, or work with the gettext pipeline. Covers the extract-translate-compile workflow, locale configuration, .po file locations, and troubleshooting.
Use when writing JavaScript code that needs localized strings. Covers the gettext.js import, domain binding via query string, and the gettext/ngettext API.
Use when working with the AI-powered translator service ($api->translator) for synchronous or asynchronous translation between system-supported languages.
| name | zolinga-intl-translations-html |
| description | Use when writing HTML that needs static translation via gettext attributes. Covers the gettext attribute syntax, gettext-context, nested element translation, meta tag, and translation modes. |
| argument-hint | <module-name> |
gettext-context to disambiguate. Place the context attribute on an element with gettext or any ancestor element if it applies to multiple strings. Always try to place it as close to the gettext element as possible to avoid unnecessary context on otherwise unambiguous strings.<void> elements (those are removed on output by zolinga-cms) and marking each chunk separately.gettext-context for short or ambiguous strings that could have different translations depending on context. Examples: "Sign Up" (registration step vs newsletter), "Monitor" (verb vs noun), "sources" (citation toggle vs water sources), CTA buttons like "Start Your Free Trial" vs "Try Risk-Free".<void gettext="."> to split long paragraphs into smaller, independently translatable sentences. This gives translators manageable chunks and allows reusing translations across pages.<void gettext="."> (or a single parent with gettext="."), not each inline element separately. Splitting a sentence into disconnected parts breaks translation context and produces poor results. Example:
<!-- WRONG: two disconnected parts of one sentence -->
<span gettext=".">Please download the PDF to view it:</span>
<a href="file.pdf" gettext=".">Download PDF</a>
<!-- CORRECT: one translatable unit with nested link as placeholder -->
<void gettext=".">Please download the PDF to view it: <a href="file.pdf">Download PDF</a></void>
Add <meta name="gettext" content="translate"/> in <head>:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="gettext" content="translate"/>
<title gettext=".">My Page</title>
<!-- TRANSLATORS: This is a navigtion menu title text - keep it as short as possible -->
<meta name="cms.title" gettext="default:content" content="My Page">
</head>
<body>
<h1 gettext=".">Hello, World!</h1>
<img alt="Company logo" gettext="alt" src="logo.png"/>
</body>
</html>
The gettext attribute is a whitespace-separated list of keywords:
| Keyword | Meaning |
|---|---|
. | Translate element's text content |
title | Translate the title attribute |
alt | Translate the alt attribute |
content | Translate the content attribute (for <meta>) |
my-module:title | Use domain my-module instead of default |
.#a3f2b1 | Hash suffix (added by extractor, do not add manually) |
CRITICAL RULE — NEVER add #hash suffixes manually. The hash suffixes (e.g. .#a3f2b1, content#4db541) are computed and inserted automatically by bin/zolinga gettext:extract using a special calculation. When marking content as translatable:
gettext=".", NOT gettext=".#abc123"gettext="content", NOT gettext="content#abc123"gettext="default:.", NOT gettext="default:.#abc123"bin/zolinga gettext:extract to let the tool add the correct hashes.Examples:
<h1 gettext=".">Hello</h1>
<a href="#" gettext="." title="Go home">Home</a>
<img alt="Logo" gettext="alt" src="logo.png"/>
<meta name="description" content="My site" gettext="content"/>
<span gettext="my-module:.">Domain-specific text</span>
Use gettext-context on an element or any ancestor to disambiguate identical strings:
<div>
<a gettext-context="navigation" gettext=".">Home</a>
</div>
<div gettext-context="homepage">
<h1 gettext=".">Home</h1>
</div>
The extractor uses the closest gettext-context attribute on the element or its ancestors as the msgctxt in .po files.
Use gettext-context-adjacent="N" on a translatable element or any ancestor (ancestor-or-self::*) to include the text of up to N preceding and N following translatable elements as TRANSLATORS comments. This gives translators surrounding context without making those elements part of the same translatable unit.
The search uses XPath preceding::*[@gettext] and following::*[@gettext] axes, so it traverses the entire document in HTML source order regardless of nesting depth. It is not limited to siblings.
<div gettext-context-adjacent="1">
<span gettext=".">Previous item</span>
<span gettext=".">This item</span>
<span gettext=".">Next item</span>
</div>
This produces a comment like:
// TRANSLATORS: Adjacent context (-1): "Previous item"
// TRANSLATORS: Adjacent context (+1): "Next item"
The traversal collects up to N translatable elements in each direction, skipping non-translatable elements. Only elements with a gettext attribute are considered.
This is especially useful for large texts (terms of service, legal documents) where each sentence is a separate translatable <void> element. Setting gettext-context-adjacent="3" on a container gives translators surrounding context for every sentence inside it:
<div gettext-context-adjacent="3">
<void gettext=".">First sentence of terms.</void>
<void gettext=".">Second sentence of terms.</void>
<void gettext=".">Third sentence of terms.</void>
<void gettext=".">Fourth sentence of terms.</void>
</div>
Each sentence will include up to 3 preceding and 3 following translatable elements as context.
You can add comments for translators using HTML comments starting with TRANSLATORS:. These comments are extracted and included in .pot/.po files to provide context and instructions.
Three supported positions:
<!-- TRANSLATORS: CTA button for free trial -->
<button gettext=".">Start Your Free Trial</button>
<span gettext="."><!-- TRANSLATORS: Main headline -->Welcome to IPDefender</span>
<div gettext=".">
<!-- TRANSLATORS: Keep the trademark symbol ® -->
<!-- TRANSLATORS: This is a registered trademark -->
IPDefender® Protection
</div>
<!-- TRANSLATORS: Legal disclaimer - applies to entire article -->
<!-- TRANSLATORS: Do not translate trademark names -->
<article>
<h1 gettext=".">Welcome</h1>
<p gettext=".">IPDefender® protection services.</p>
</article>
<!-- TRANSLATORS: Pricing section context -->
<div class="pricing">
<h2 gettext=".">Our Plans</h2>
</div>
Extraction mechanism (in order):
For each translatable element, the extractor collects TRANSLATORS: comments in this exact order, then deduplicates:
// TRANSLATORS: This string's location in the HTML source code is /html/body/...gettext-context-adjacent attribute (if set)getNestedTranslatorsComments(): collects consecutive comment child nodes at the start of the element (stops on non-empty text or non-comment element).getPrecedingTranslatorsComments() called for each node in the ancestor-or-self::* XPath axis. For each node it collects consecutive preceding-sibling comment nodes up to the first stopper.Deduplication: After collecting all comments from steps 1-5, array_unique(array_filter(...)) removes duplicates and empty entries.
Rules:
TRANSLATORS: (case-sensitive)<!-- ... -->.po fileThe gettext="." attribute works on elements containing other elements too. Child elements become numbered placeholders:
<div gettext=".">Click <a href="/">here</a> to go to <i>homepage</i>.</div>
This appears in .po as: Click <1>here</1> to go to <2>homepage</2>.
The translator keeps the placeholders and translates around them:
msgstr "Kliknete <1>zde</1> pro navstevu <2>domaci stranky</2>."
The compiler expands placeholders back to full HTML:
<div gettext=".">Kliknete <a href="/">zde</a> pro navstevu <i>domaci stranky</i>.</div>
The <meta name="gettext" content="..."/> in the generated file controls behavior on recompilation:
| Mode | Behavior |
|---|---|
replace | File is fully regenerated from source on every compile. Default for new files. Manual edits are lost. |
cherry-pick | Only elements with gettext attribute are updated; all other HTML is preserved. Good for large articles where translators need full control of layout. |
| (no meta) | File is ignored by compiler — fully manual maintenance. |
Warning: Cherry-pick mode does NOT sync structural changes (CSS, images, new elements) from the source file — only translatable strings are updated. Use replace mode if you want structural changes reflected in the translated file.
<void>Use <void> elements to break long paragraphs into smaller translatable chunks. The <void> tags are removed on output, so the rendered HTML is identical:
<p>
<void gettext=".">If a dispute goes to court, judges rely on this evidence to confirm your ownership.</void>
<void gettext=".">Without proper documentation, it becomes much harder to prove your rights.</void>
<void gettext=".">This requirement is based on trademark laws that grant protection only when the brand owner actively defends their mark.</void>
</p>
This gives translators manageable sentences instead of one huge block, and allows reusing translations across pages.
Always mark citations, quotes, and attribution text as translatable. Legal citations and source text need translation just like any other content:
<cite itemprop="name" gettext=".">
Federal Trade Commission: Corrected Trial Brief, 2021
</cite>
<quote cite="https://example.com" gettext=".">
Therefore, once acquired, trademark rights may be lost or weakened...
</quote>
<a role="show-sources" gettext-context="citation toggle" gettext=".">sources</a>
Run bin/zolinga gettext:extract --domains=my-module,default to generate .po files, then translate and compile.
Important: gettext:extract modifies source HTML files in place — each keyword in every gettext attribute receives a #-prefixed 6-character hash suffix that uniquely identifies the element. For example, gettext="." becomes gettext=".#a3f2b1" and gettext=". title" becomes gettext=".#d2bc00 title#1396ff". These hashes link source elements to their translations across files. Commit the updated source files after extraction.
NEVER add hash suffixes manually when marking content. Write gettext="." and let the extractor add .#a3f2b1. Only the extractor knows the correct hash calculation.
Note that all translations not in a module but in data folders like data/ or public/data can be translated using the built-in default domain. Use --domains=default to extract and compile these translations.
For testing the translation workflow without affecting production domains, use the test domain:
bin/zolinga gettext:extract --domains=test
bin/zolinga gettext:compile --domains=test
The test domain scans files and creates output in data/zolinga-intl/gettext-test/ folder. This is ideal for testing behavior and experimenting with the translation pipeline.
See also: zolinga-intl-multilingual-support for the full pipeline.