how to properly provide rules for translations

[davidstevenrojas]

Hello!

I am trying to use this tool to help me translate some guides in batch, I have some instructions that I wanted the translator to follow, so I created a pyproject.toml file with rules like:

[tool.gpt-po-translator]
default_context = """

Rules:

Preserve all formatting exactly: \n, spacing, punctuation, quotes, variables {}, code blocks, AsciiDoc syntax, placeholders, href, xref attributes, and any HTML entity as in the original document.

 Do NOT translate parameter names, variable names, annotations, method names, or code-related identifiers (for example: query parameters, field names, function names).

Links rule:
   - If the source has link:https://...[], keep it identical.
   - If the source has a bare URL or text without link:, write the translation using correct AsciiDoc format: link:URL[TEXT].

Maintain URLs and link structures exactly.

"""

However, after translating I am finding the HTML entities are transformed and also the xref attributes are removed and replaced with other characters, here one example:

I am using a command like this to perform the translation, using my Anthropic key:

gpt-po-translator --folder /home/davidstevenrojas/gpt-po-translator --fix-fuzzy --no-ai-comment -v --bulk --bulksize 50

Is the default context a proper place for these rules?
Is there a way to control this output in the translation?
It would be great to know if I am off base with attempting to enforce such rules, they have worked great when applying them manually on small pieces of content from po files in an agentic terminal, I wanted to achieve a similar behavior in batch using gpt-po.

Thanks for any insight you can provide.

[brammittendorff]

Will respond upcomming week, may I ask which framework you are using or which language to compile the po's and mo's?

[davidstevenrojas]

hello!
Thanks for getting back to me, I am playing around with the Quarkus ES po files from https://github.com/quarkusio/es.quarkus.io/tree/main/l10n/po/es_ES/_guides, from the main project page: https://github.com/quarkusio/es.quarkus.io, I undersand they are using https://www.po4a.org/ to get the po's.

Does this answer your question?
Thanks!

[pescheck-bram]

hello! Thanks for getting back to me, I am playing around with the Quarkus ES po files from https://github.com/quarkusio/es.quarkus.io/tree/main/l10n/po/es_ES/_guides, from the main project page: https://github.com/quarkusio/es.quarkus.io, I undersand they are using https://www.po4a.org/ to get the po's.

Does this answer your question? Thanks!

Yes perfect, I will try to reproduce this.

[pescheck-bram]

Thanks for the detailed explanation!

Important clarification: What you've put in default_context is not context, it's translation rules/instructions.

The default_context option follows the https://www.gnu.org/software/gettext/manual/html_node/Contexts.html, which exists to disambiguate identical strings with different meanings:

msgctxt "verb"
msgid "Open"
msgstr "Abrir"

msgctxt "adjective"
msgid "Open"
msgstr "Abierto"

Context vs Rules:

Context (what the tool expects)	Rules (what you wrote)
"medical device interface"	"Preserve all formatting exactly"
"button label"	"Do NOT translate parameter names"
"Quarkus documentation"	"Maintain URLs and link structures"

Context tells the AI what the text is about so it picks the right word meaning.
Rules tell the AI how to translate that's a different thing entirely.

The tool wraps your text as:
CONTEXT: {your rules here}
IMPORTANT: Choose the translation that matches this specific context and usage.

The AI sees your formatting rules but they're framed as "context for word choice" not as instructions to follow. This is working as designed.

What you CAN do:

• Use actual context: default_context = "Quarkus technical documentation with AsciiDoc markup"
• Reduce --bulksize to 5-10 for better results

[davidstevenrojas]

thanks @pescheck-bram for your feedback, I totally understand the difference now.
I also managed to see the --translation-rules idea, then it was edited and I no longer see it, isnt that feasible? or are you open to accept that as a contribution if it gets implemented?
Thanks again for your time. Appreciate it.

[pescheck-bram]

thanks @pescheck-bram for your feedback, I totally understand the difference now. I also managed to see the --translation-rules idea, then it was edited and I no longer see it, isnt that feasible? or are you open to accept that as a contribution if it gets implemented? Thanks again for your time. Appreciate it.

Honest answer: --translation-rules is technically possible to implement, but it probably won't fully solve your problem.

Why:

• The prompt is already quite large with built-in formatting rules ("Keep special characters, placeholders, and formatting intact", "If a term should not be translated, keep it as is", etc.) - and your AsciiDoc is still getting mangled see: http://github.com/pescheckit/python-gpt-po/blob/main/python_gpt_po/services/translation_service.py#L255-L298
• AI models don't reliably follow complex formatting rules, especially in bulk mode
• Even with explicit instructions, models often "forget" rules mid-batch or interpret them loosely
• AsciiDoc syntax preservation and HTML entity handling are particularly tricky - the AI doesn't deeply understand these formats
• Your rules worked in an agentic terminal because you were doing small pieces with direct oversight

What would actually help:

1. Much smaller --bulksize (5-10) - biggest impact
2. Post-processing validation to catch/fix mangled syntax
3. Possibly a specialized prompt or even fine-tuning for technical documentation

On contributing:
The feature could be added, but I want to set expectations - it would be a "best effort" instruction injection, not a guarantee. Adding more rules to an already large prompt may not improve results. For your Quarkus/AsciiDoc use case, you may still need additional tooling or manual review.

If you still want to try it, reducing --bulksize to 5-10 with default_context = "Quarkus technical documentation with AsciiDoc markup" is your best bet right now.