Languages - FHIR v5.0.0-ballot

Release 5 Ballot

This page is part of the FHIR Specification (v5.0.0-ballot: R5 Ballot - see ballot notes). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4

7.15 Multi-Language support in FHIR (Localization/Internationalization)

FHIR Infrastructure icon

Work Group

Maturity Level: n/a

Standards Status: Informative

In general, with regard to human language, the content in resources falls into one of three categories

The content is language neutral
The content has a specified language
There are multiple representations of the same content in different languages

The vast majority of clinical content is language neutral - the language is either unknown or unspecified, and assumed to be in the natural language predominant in the implementation environment. Note that this doesn't mean that the content is all in the same language - often, snippets of other language content will creep in where patients or providers themselves are multi-lingual, but there is no formal tracking for such content, and it will often be translated in situ for the benefit of all users.

While most applications are entirely language neutral, many healthcare applications must deal with multi-lingual content. This page provides a roadmap to the facilities in the FHIR specification for supporting multiple languages.

FHIR offers the following facilities for dealing with languages:

Language tag on Resource and Narrative
Translation Extension
Translations on CodeSystem and ValueSet
Translatable extension on element definition
Language Tags on HTTP requests
Languages in Names and Addresses

7.15.1 Specification

The specification itself is published and balloted in English (US). There are projects to translate this to other languages (e.g. Russian icon and Japanese icon ), but these are generally not well maintained.

One consequence of the way the specification works is that the element names (in either JSON or XML) are in English. These should be considered as references into the specification; they’re never meant to be meaningful to any one other than a user of the specification itself, and are never intended to be displayed to end-users of any healthcare application. For users of the specification, a multi-language glossary exists, and contributions are welcome.

What may be displayed to users are the display terms for codes and elements, which can be managed as described below. Multiple languages are provided for some codes/elements and languages:

Further contributions from affiliates or implementers is welcome.

7.15.2 Language tag on Resource and Narrative

Every resource has an optional language element that is the base language for the content of the resource. Note that this does not require that all the content of the resource be in the specified language; just that unless otherwise specified, this is the default language of the content.

In addition, an xml:lang attribute can be specified on the html:div element (or any element in the HTML). This can be used to specify a language in addition to the resource language. Note that it doesn't really make sense to specify a different language on the narrative than on the resource itself; the xml:lang attribute is allowed to support natural language processing of the narrative.

Where resources contain the same documentation in several different languages, each different languages should use a div element with an XHTML lang attribute in the root div. By default, all languages will be displayed to a user, but multi-language aware applications can filter the content by language and only display the language that is relevant to or chosen by the patient.

See the W3C documentation on Language declarations icon for further information.

Note that the choice of locale from the "Accept-language" headers MAY change syntax of resource narrative (e.g., date formats, number formats).

7.15.3 Translation Extension

All human readable character content (any elements of type string and markdown) has the same language as that specified by the resource language element. Whether or not a language is specified, translations may be provided for any human readable character content. Translations are provided using the translation extension:

{ 
  "url" : "http://hl7.org/fhir/StructureDefinition/translation",
  "extension" : [{
    "url" : "lang", 
    "valueCode" : "de"
  },{
    "url" : "content",
    "valueString" : "einige übersetzte Wörter"
  }]
}

Multiple translations can be provided if more than one language is required.

7.15.4 Translations on CodeSystem and ValueSet

Concepts defined in CodeSystem resources can have one or more designations that provide additional representations for the concept (CodeSystem.concept.designation):

{
  "code": "de",
  "display": "German",
  "designation": [{
      "language": "nl",
      "value": "Duits"
    },{
      "language": "ru",
      "value": "Немецкий"
    },
    {
      "language": "zh",
      "use": {
        "system": "http://terminology.hl7.org/CodeSystem/designation-usage",
        "code": "display"
      },
      "value": "德语"
    }
  ]
}

The base display ("German" in this case) is in the language specified on the resource. Applications using the code system can pick the appropriate language based on the context and/or relevant parameters when using the code system. Alternate designations can also be specified when concepts are include in value sets (ValueSet.compose.include.concept.designation).

7.15.5 Translatable extension on element definition

All elements in FHIR resources or datatypes are defined by an ElementDefinition. Element Definitions provide several different descriptions for each element, the most important of which are label and definition. These (and other string and markdown properties on the element definition can have translations using the extension shown above.

In addition to this, elements can be marked with the translatable extension:

{ 
  "url" : "http://hl7.org/fhir/StructureDefinition/elementdefinition-translatable", 
  "valueBoolean" : true
}

This indicates that applications should consider supporting translations when reading/writing this element.

7.15.6 Language Tags on HTTP requests

HTTP Requests can include a header to indicate which language is requested:

Accept-Language: de-DE

The header can contain multiple languages, with weighted preferences. Servers can use the header to return the correct language if they are able. If the request is a search, the server may choose to limit matches to those that contain the correct language, though this might be unsafe.

HTTP Responses can include a header to indicate which language is in the resource:

Content-Language: en-US

If present, the content language header must match the language of the resource (if specified).

Languages in Names and Addresses

7.15.7 Languages in Names and Addresses

Names and addresses are one area of special difficulty with regard to multiple languages. Inherently, names and addresses only have one language, but they may have approximations in other languages, or people may choose to take entirely different names for different cultures. Some of the name examples illustrate how this is handled.

One common practice in some cultures is the represent the same name twice, in local and western scripts. These can be differentiated by the script portion of the language extension:

  <name>
    <extension url="http://hl7.org/fhir/StructureDefinition/language">
      <valueCode value="ru-RU-Cyrl"/>
    </extension>
    <family value="ЕМЕЛИН" />
    <given value="ИВАН" />
    <given value="ВЛАДИМИРОВИЧ" />
  </name>
  <name>
    <extension url="http://hl7.org/fhir/StructureDefinition/language">
      <valueCode value="ru-RU-Latn"/>
    </extension>
    <family value="EMELIN" />
    <given value="IVAN" />
    <given value="VLADIMIROVICH" />
  </name>

The different scripts can also be differentiated by the Unicode subsets that they contain, but this is not always convenient.