Guidance for FHIR IG Creation
0.1.0 - CI Build
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
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.
translations/{lang}/{format}/{ResourceType}-{id}.{ext} in each of the three formats, for example
translations/fr/po/StructureDefinition-MyPatient.po.input/translations/{lang}/{ResourceType}-{id}.{ext}, for example
input/translations/fr/StructureDefinition-MyPatient.po.translations/ now carry your translations forward, so new or changed strings stand out.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.
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.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.
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.