Guidance for FHIR IG Creation
0.1.0 - CI Build International flag

Guidance for FHIR IG Creation, published by HL7 International - FHIR Management Group. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/FHIR/ig-guidance/ and changes regularly. See the Directory of published versions

Translating Resources

Two folders are involved, and they are laid out differently. The build writes into translations, in a subfolder per format so that you can pick one. You write into input/translations, flat, one file per resource.

  Path
Generated by the build, for you to translate translations/{lang}/{po|xliff|json}/{ResourceType}-{id}.{ext}
Your translation, read by the next build input/translations/{lang}/{ResourceType}-{id}.{ext}
Your translated narrative page input/translations/{lang}/pagecontent/{page}.md

This is the cycle you repeat until the translations are complete.

  1. Build the IG. For every resource with translatable text, the publisher writes a file to translations/{lang}/{format}/{ResourceType}-{id}.{ext} in each of the three formats, for example translations/fr/po/StructureDefinition-MyPatient.po.
  2. Pick one format. PO, XLIFF or JSON. See Translation formats.
  3. Translate the file, by hand, with a translation tool, or with AI followed by review.
  4. Save it into the IG directly in the translation folder, without the format subfolder: input/translations/{lang}/{ResourceType}-{id}.{ext}, for example input/translations/fr/StructureDefinition-MyPatient.po.
  5. Rebuild. The translated text appears in the rendered pages for that language, and the generated files in translations/ now carry your translations forward, so new or changed strings stand out.

What gets translated

  • StructureDefinition: for each element, the definition, plus requirements, comment, meaningWhenMissing, orderMeaning, isModifierMeaning and binding.description when present.
  • CodeSystem: display, definition and designations for each concept, plus string and markdown extensions.
  • Questionnaire: item text, plus prefixes, options and initial values when present.
  • Resource metadata: name, title, purpose, description, publisher, copyright.

Translating resources from packages you depend on

Translations for content you do not own should come from a translation source that is released on its own schedule, not from a new release of that content. A French rendering of an element definition in IPS should not have to wait for the next IPS release, and a corrected label in the publisher should not have to wait for the next publisher release. The tooling supports this; use it rather than forking.

  • A language pack for that specification. A pack is not limited to FHIR core and THO: it can depend on any package and translate that package's resources. One pack per language and specification, published on its own cadence, is the right home for translations that several IGs will share. See Language packs.
  • Translation files in your own IG. For a fix you need now, or a translation only your IG needs, put a translation file for the upstream resource in your own input/translations/{lang} folder, named after that resource, for example StructureDefinition-Composition-uv-ips.po. Start with an empty file: the build then generates the strings to translate under translations/, exactly as for your own resources, and turns your translation into a CodeSystem supplement that ships in your IG's package. Rendering does not yet use it. As of the current publisher, the supplement is labelled with the IG's default language rather than the translation's, and the renderer only consults supplements for code displays, not for element definitions inherited from an upstream profile. So the file is produced and packaged, but the upstream text still renders in the source language. The same limitation applies to profile text in a language pack; language packs do work for code displays. Treat this option as the intended route, not a working one, until the tooling catches up.
  • Forking the upstream IG and depending on the fork also works, but it ties you to maintaining the fork. Prefer the two options above.

Text generated by the publisher itself follows the same principle: the -po-dir flag applies PO files at build time without a publisher release. See Publisher-generated text.

How this works

Each translatable string gets a stable key derived from the resource id and element path, for example the element id in a StructureDefinition or the concept code in a CodeSystem. Sub-properties get sub-keys of the form item@property. The publisher matches your translation file to the resource by file name and to the string by key, which is why renaming a resource id or element id orphans its translations.

The publisher lists the files directly in each translation-sources folder and picks up any whose name starts with {ResourceType}-{id} and ends in .po, .xliff or .json. The language comes from the folder path, or from a -{lang} part of the file name if you keep several languages in one folder. The po, xliff and json subfolders exist only in the generated translations/ output, so that you can pick a format; they are not expected on the input side.