Experimental. This skill has not been verified against a real task since its last change. Verify its output before relying on it.

1. Locate the guide. From the working directory, expect

   input/pagecontent/

   together with a

   sushi-config.yaml

   or an

   ig.ini

   .

   scripts/ig-translate.sh

   checks this itself and exits 2 with a message if the directory is not an IG project — it deliberately does not report "nothing to translate", which is what a silent failure here looks like.
2. Derive the language pair — never assume it. Read the guide's own

   sushi-config.yaml

   :
   yaml

   parameters:
     i18n-default-lang: en        # the SOURCE language
     i18n-lang:
       - de                       # the TARGET language(s)
     translation-sources:
       - input/translations/de

   • i18n-default-lang

     is the source: the language

     input/pagecontent/

     is written in, and the authoritative text.
   • each

     i18n-lang

     entry is a target: a language that gets a rendering under

     /<lang>/

     .
   • If

     i18n-default-lang

     is absent, the publisher's default applies and the source language is not declared. Report that and ask rather than guessing — a guess here puts every file in the wrong place.
   • If no

     i18n-lang

     is configured, there is no target language yet. Adding one is a change to the guide's configuration and a decision for its maintainer, not for this skill.
   This is the step that must not be skipped. The MII reversed its own default from German to English once; a skill that had hard-coded the old direction would have placed every file wrongly while reporting success.
3. Build first. Resource supplements need generated resources: the publisher writes

   fsh-generated/resources/

   and generates supplement templates per resource on each build. Translating before a green build means inventing

   msgid

   values, which is fabrication.
4. Check whether this is the guide's problem or the template's. Language support is usually split between an IG and the template package it renders with, and the split is about responsibility, not paths:
   • This skill covers the guide's own content: supplements and translated pages under

     input/translations/<lang>/

     .
   • A template package owns the language mechanism and policy — language-neutral header/footer/CSS, inherited UI-string catalogues, and the choice of default language.
   For the MII KDS module template that template package is https://github.com/forschungsgruppe-digital-health/ig-template-mii-kds, which carries its own skill for those obligations. If the task is "keep the template's overrides language-neutral", that is the template's problem, not this one.

de

Resolve the script path first. The commands below name the tool relative to this skill's own directory, not to your working directory — which is the project you are operating on. Set

SKILL_DIR

to the directory containing this

SKILL.md

(you just read it, so you know where it is) and use it in every invocation:

bash

SKILL_DIR=<the directory containing this SKILL.md>   # e.g. .claude/skills/fhir-ig-translation

Running a bare

scripts/...

from the project root does not merely fail — if the project happens to have its own

scripts/

directory with a same-named file, it silently runs that instead.

1. Scan to get the target path for every page and resource:
   bash

   bash "$SKILL_DIR/scripts/ig-translate.sh" --scan <lang>              # cwd = the guide's root
   bash "$SKILL_DIR/scripts/ig-translate.sh" --scan <lang> path/to/ig   # or point at it

   The language argument is required — the script refuses to default it, so no run can silently translate into a language nobody chose.
2. Resource supplements. One file per StructureDefinition, CodeSystem or Questionnaire at

   input/translations/<lang>/<Type>-<id>.po

   , where

   msgid

   is the exact source text from

   fsh-generated/resources/<Type>-<id>.json

   and

   msgstr

   is the translation. Copy the publisher's generated template rather than hand-writing the

   msgid

   .
3. Narrative pages. One translation per page at

   input/translations/<lang>/pagecontent/<same-filename>.md

   — the same file name, the same structure, the same links, FHIR identifiers unchanged. Never a

   <name>-<lang>.md

   sibling in

   input/pagecontent/

   : the toolchain renders that as a separate page, not as a translation.
4. Menu, if the guide has one:

   input/translations/<lang>/includes/menu.xml

   , mirroring

   input/includes/menu.xml

   . A

   menu:

   property in

   sushi-config.yaml

   generates one untranslatable menu and competes with this — it must not be used alongside.
5. The IG-level catalogue

   input/translations/<lang>/ImplementationGuide-<ig-id>.po

   . Not a resource supplement and not optional: without it the

   pages:

   -tree page titles stay in the default language, so

   /<lang>/

   renders localized page bodies under default-language breadcrumbs.

   <ig-id>

   is the

   id

   of

   fsh-generated/resources/ImplementationGuide-<id>.json

   ; build the unit set from that file's

   definition.page

   tree — the authoritative page set — using

   input/includes/menu.xml

   only as a wording seed, and emit an empty

   msgstr

   plus a review flag for every title left untranslated.
   The sibling

   mii-ig-migration

   skill bundles a generator for exactly this file. It is a precondition, not an assumption: a consumer may have installed this skill alone, in which case the sibling path does not exist. Check first, and when it is absent either install it with the pinned command below or write the units by hand — never proceed on a path that does not resolve. Invoke it through a resolved

   $SKILL_DIR

   , never a bare

   scripts/…

   , which the project's own

   scripts/

   would shadow:
   bash

   GEN="$SKILL_DIR/../mii-ig-migration/scripts/gen-page-title-po.py"
   if [ -f "$GEN" ]; then python3 "$GEN" --help; else
     echo "gen-page-title-po.py not installed — install the sibling skill, or write the units by hand:"
     echo 'npx skills add "https://github.com/forschungsgruppe-digital-health/agent-skills/tree/v0.12.0" --skill mii-ig-migration --agent claude-code codex --yes'
   fi

   The

   /tree/<ref>

   form is what pins;

   owner/repo@<ref>

   does not — in that CLI

   @

   introduces a skill name and the command silently installs from the default branch.
   Read that script's header before regenerating an existing catalogue: the same file also carries hand-added units (the guide's

   title

   , per-artifact names) that the generator does not own, and its header states how it treats them.
6. Validate, then build:
   bash

   bash "$SKILL_DIR/scripts/ig-translate.sh" --validate <lang>

   Findings (

   [WARN]

   ) exit 1; a run that finds nothing to validate says so explicitly and exits 0 — add

   --strict

   to make an empty translation set fail too, which is the right wiring for CI.
7. Bilingual human review is mandatory before the translated rendering is trusted. Mark every machine translation

   TODO:REVIEW

   until a human has signed it off.

1. Fill in

   references/harvest-config.yaml

   : the source of the target-language text (a parallel rendered guide for narrative; FSH

   translation

   extensions or

   designation

   s for resource texts) and the page/artefact mapping.
2. Resources: move the existing designations or translation extensions into

   input/translations/<lang>/<Type>-<id>.po

   . The page titles of the existing rendering are a translation seed for the IG-level catalogue (step 5), not a substitute for it.
3. Narrative: copy the page content into

   input/translations/<lang>/pagecontent/<name>.md

   , citing the source path per page. Invent nothing; mark anything unclear

   TODO:REVIEW

   .
4. Validate, build and review as above.

fhir2.base.template

input/pagecontent/<name>.md

input/translations/<lang>/pagecontent/<same-filename>

/<lang>/

description

definition

input/translations/<lang>/<Type>-<id>.{po|xliff|json}

input/includes/menu.xml

input/translations/<lang>/includes/menu.xml

title

definition.resource.name

input/translations/<lang>/ImplementationGuide-<ig-id>.po

PublisherIGLoader

importFromTranslations

TRANSLATION_SUPPLEMENT_RESOURCE_TYPES

#:

es

es/artifacts.html

description

publisher

name

.description

name

pages:

<title>

ImplementationGuide.definition.page.title

.po

titlelang

breadcrumblang

temp/pages/_data/pages.json

titlelang

pages:

ImplementationGuide-<id>.json

msgstr

FHIR/multi-lang-test-ig

es

nl

dev

fragment-pagebegin.html

input/includes/breadcrumb-titles-de.txt

dev

.po

concept.display

concept.definition

.po

references/translate-spec.md

concept.display

concept.definition

i18n-lang

translation-sources

.po

• An earlier version of this skill used a

  <name>-<lang>.md

  sibling for pages and stated that narrative pages were "not yet" renderable. Both were wrong. The correct mechanism is a translation-source folder, as HL7's own

  FHIR/multi-lang-test-ig

  demonstrates.
• This skill claimed that

  ImplementationGuide-<id>.po

  is "ignored by the Publisher", that there is "no supplement mechanism" for the IG title, and that default-language breadcrumbs on

  pages:

  -tree pages are "a toolchain limitation, not a defect" requiring the MII template's

  breadcrumb-titles-de.txt

  workaround. All wrong: it generalized

  TRANSLATION_SUPPLEMENT_RESOURCE_TYPES

  — which really does restrict resource supplements — to the IG resource, which is translated by a separate load-time import. The page-title mechanism was verified on 2.2.11 (our pin) against an MII KDS module with the template's breadcrumb override deleted; HL7's reference IG ships such a

  .po

  and its live build — produced by 2.0.13 — renders

  es

  /

  nl

  breadcrumbs from it. That says nothing about since when the publisher supports this: no support floor is claimed, and none should be inferred from those two version numbers. The real cause of "translations do not apply" is usually the

  translation-sources

  footgun in the table above.

bash "$SKILL_DIR/scripts/ig-translate.sh" --validate <lang>          # --strict: empty set fails too

• Exit 2 with a clear message when run outside an IG, or when the language argument is missing — a silent empty scan is the failure mode this guards against.

• --validate

  reports

  [OK]

  per supplement and per page, and no

  [WARN]

  ; any

  [WARN]

  exits 1, and its summary line states how many supplements and pages were actually checked. "Checked: 0" with exit 0 is an explicit nothing to validate, never a claim that translations are valid (

  --strict

  turns it into a failure).
• The script WARNs when

  <lang>

  is not among the guide's

  i18n-lang

  targets or when

  i18n-default-lang

  is undeclared — a best-effort echo of Preconditions 2, not a substitute for it.
• Every

  .po

  filename is

  <Type>-<id>

  and matches a real

  fsh-generated/resources/<Type>-<id>.json

  — including

  ImplementationGuide-<ig-id>.po

  , which is a legitimate file, not a naming error.
• No supplement exists for an unsupported type, and no

  menu.po

  exists — the publisher ignores both.
• Every

  i18n-lang

  entry has a matching

  translation-sources

  entry; otherwise that language's

  .po

  files are ignored silently.
• Every translated page has a source page of the same name under

  input/pagecontent/

  .
• After a build,

  /<lang>/

  artefact pages show the translated element texts and

  /<lang>/

  narrative pages render in the target language.
• After a build with an IG-level

  .po

  ,

  /<lang>/

  breadcrumbs, the TOC page body and the browser

  <title>

  are in the target language, and

  temp/pages/_data/pages.json

  carries a

  titlelang

  that differs from the default-language title for every page in the

  pages:

  tree. A page whose

  titlelang

  still equals the source title has no unit, or an empty

  msgstr

  , or the language is missing from

  translation-sources

  .
• The default-language

  input/pagecontent/

  and the FSH sources are unchanged —

  git diff

  on them is empty.

• The default-language source stays leading and binding. A translation is a rendering aid, never the normative text. Which language that is comes from

  i18n-default-lang

  , not from this file.
• Never change the source. Translations are additive under

  input/translations/<lang>/

  .
• FHIR identifiers stay untranslated —

  name

  ,

  id

  , codes and canonical URLs are not language.
• No invention. Mark every machine translation

  TODO:REVIEW

  ; bilingual human review is mandatory.
• Only on confirmation. The default is a dry-run scan.
• Propose, do not merge. Deliver changes as a pull request, and determine the target branch from the repository's own convention — do not assume one. An earlier version of this skill hard-coded

  dev

  , which is one repository's convention and wrong everywhere else.

• Measuring or comparing guides — see

  fhir-ig-analysis

  .
• Migrating a guide onto the MII KDS module template — see

  mii-ig-migration

  , which sets translation up as one step of a migration and then hands over here.
• A template package's language mechanism and policy — a different repository's concern; see Preconditions 4.
• Choosing the guide's languages. Adding an

  i18n-lang

  entry changes the guide's configuration and is its maintainer's decision.
• Judging whether a translation is good. That is the mandatory human review, not this skill.

• references/translate-spec.md

  — the full mechanics, file conventions and formats.

• references/harvest-config.yaml

  — configuration schema for harvest mode.

• references/triggers.md

  — the Gate 3 prompt set.

• scripts/ig-translate.sh

  — scan and validate; dry-run by design, it writes nothing. It scans for the IG-level catalogue alongside the resource supplements and accepts it in

  --validate

  ; genuinely unsupported types still WARN. Validation findings exit 1;

  --strict

  also fails an empty translation set.

skills/ig-translate

forschungsgruppe-digital-health/mii-kds-module-template

b5beedb17a66a4397d597429668c7b6d54202c62

ig-translate

forschungsgruppe-digital-health/mii-kds-sample-ig-inoffiziell

• The helper now ships with the skill. It previously lived in the source repository's

  scripts/

  and was referenced by parent traversal.

• scripts/ig-translate.sh

  operates on the current working directory and detects whether it is an IG project. It previously did

  cd "$(dirname "$0")/.."

  , assuming it sat in

  <module-repo>/scripts/

  ; installed as part of a skill that

  cd

  reaches the skill directory, and the scan would have reported every page as missing.
• The

  dev

  branch target was removed from the description and the guardrails, and replaced by discovering the repository's own convention.
• The language pair is derived, not assumed. The inherited skill was written for one direction (

  en

  →

  de

  ) and for MII KDS modules specifically, which made a

  fhir-

  prefix on its name an overclaim. It now reads

  i18n-default-lang

  and

  i18n-lang

  from the guide being worked on, the script requires an explicit language argument instead of defaulting to

  de

  , and the mechanics are stated for any language pair. That is what earns the prefix.

kerndatensatz-dokument

--validate

--strict

<lang>

page_map

allowed-tools

mii-kds-dokument-ig-inoffiziell

docs/reports/dry-run-2026-07-31/

pages:

ImplementationGuide-<id>.po

• Our own build on our own pin (IG Publisher 2.2.11) — the migrated MII KDS Dokument guide with the template's breadcrumb override deleted and 23

  page.title

  units supplied:

  /de/

  breadcrumbs German including the root label "Inhaltsverzeichnis", the TOC page body German, the browser

  <title>

  German, and

  temp/pages/_data/pages.json

  titlelang

  differing en/de for all 23 pages (zero before). Build health unchanged (sushi 0 errors, QA err=7 = the established baseline). The left-hand nav,

  IG.description

  ,

  IG.publisher

  ,

  IG.name

  and artifact names were not observed on 2.2.11 and are not claimed for it.
• HL7's reference IG

  FHIR/multi-lang-test-ig

  , live build produced by publisher 2.0.13 — localized

  es

  /

  nl

  breadcrumbs, a translated IG title in the

  /es/

  header, translated artifact names on

  /es/artifacts.html

  , and

  fr

  (in

  i18n-lang

  , absent from

  translation-sources

  ) as a controlled negative. A different publisher version from ours; kept separable in the tables.
• Prior art in our own organisation: both MII template repos already carry a correct catalogue on their

  dev

  branch, and

  ig-template-mii-kds

  records the same mechanism in the MII's own

  kerndatensatz-basis

  module, "verified 2026-07-30".

dev

mii-ig-migration

concept.display

definition

references/translate-spec.md

scripts/ig-translate.sh

ImplementationGuide-<id>.po

scripts/