Documentation translation is a different beast from UI string translation: the source is prose, the structure carries meaning, and the unit of translation is usually a paragraph or a section rather than a single label. Most teams that try to push their Markdown docs through a TMS quickly discover that the TMS does not speak Markdown — it speaks PO, XLIFF, or its own proprietary CAT format. A Markdown-to-PO step is therefore the standard onramp for any docs-translation pipeline, and getting the section-to-key mapping right is what separates a usable translation memory from a perpetually-fragmented one.
i18n-convert walks the Markdown document, ignores YAML front matter (the --- locale: en --- block at the top), and generates a deterministic key for every translatable section based on the heading hierarchy. The top-level heading becomes the root key; subsequent headings get appended as dot-separated slugs (welcome.getting-started, welcome.faq.how-do-i-reset-my-password); body content directly under a heading becomes the msgstr value for that heading's key. Lists, code-block boundaries, and multi-line paragraphs are preserved as multi-line msgstr strings using PO's standard line-continuation syntax. The result is a gettext catalog that any standard translator tool can ingest, and that produces a stable diff each time the docs are refreshed — only changed sections show up as modified entries.
Command
i18n-convert simple.md --to po -o docs.po
Input
---
locale: en
---
# Welcome
Hello and welcome to our application.
## Getting Started
Follow these steps to get started:
1. Create an account
2. Set up your profile
3. Start using the app
## FAQ
### How do I reset my password?
Go to Settings > Security > Reset Password.
### How do I change my email?
Go to Settings > Account > Change Email.
Output
msgid ""
msgstr ""
msgid "welcome"
msgstr "Hello and welcome to our application."
msgid "welcome.getting-started"
msgstr ""
"Follow these steps to get started:\n"
"\n"
"1. Create an account\n"
"2. Set up your profile\n"
"3. Start using the app"
msgid "welcome.faq.how-do-i-reset-my-password"
msgstr "Go to Settings > Security > Reset Password."
msgid "welcome.faq.how-do-i-change-my-email"
msgstr "Go to Settings > Account > Change Email."