How to use multilingual search

Multilingual search

FHIR specifies the translation extension to store translations from the base language of a resource to other languages. In this post, we will cover how to search through resources by specifying the language.

1. Create a Resource with Translations:

Define a FHIR resource (e.g., Location) with translations for specific fields using the FHIR translation extension. Specify translations for each language by including the lang and content sub-extensions.

POST /fhir/Location

resourceType: Location
id: loc-1
status: active
name: Location name
_name:
  extension:
    - url: http://hl7.org/fhir/StructureDefinition/translation
      extension:
        - url: lang
          valueCode: fr-CA
        - url: content
          valueString: Clinique médicale du cœur de la ville
    - url: http://hl7.org/fhir/StructureDefinition/translation
      extension:
        - url: lang
          valueCode: en-CA
        - url: content
          valueString: Downtown Heart Medical Clinic

2. Enable Multilingual Search:

Activate the _search-language feature in Aidbox by providing the following environment variable BOX_FEATURES_MULTILINGUAL_ENABLE__SEARCH__LANGUAGE and setting it to true. This allows you to use the non-FHIR search parameter [_search-language](https://www.health-samurai.io/docs/aidbox/api-1/fhir-api/search-1/search-parameters-list/_search-language) to specify the locale for searching.

3. Perform Searches in Specific Languages:

Use the _search-language parameter in your API request to specify the desired language for searching (e.g., French or English). For example, to search for locations by name in French:

GET /Location?_search-language=fr-CA&name=Clinique

To search locations by name in English:

GET /Location?_search-language=en-CA&name=Downtown

4. Alternatively, you can use the Accept-Language Header:

Instead of the _search-language search parameter, you can enable the use of the Accept-Language HTTP header by providing the environment variable BOX_FEATURES_MULTILINGUAL_USE__ACCEPT__LANGUAGE__HEADER and setting it to true. This allows you to specify the language directly in the request header. So, instead of using the following search query:

GET /Location?_search-language=fr-CA&name=Clinique

You can perform the following request:

GET /Location?name=Clinique
Accept-Language: fr-CA

5. Translate Concepts:

Use the $translate-concept endpoint to retrieve translations of specific terminology concepts based on their code and system. Specify the target language and the list of concepts to fetch their translations. In the following example, we will fetch translations to French Canadian for LOINC terminology concepts.

POST /$translate-concepts

language: fr-CA
concepts:
- system: http://loinc.org
  code: 1-8
- system: http://loinc.org
  code: 2-6

In response, you will receive concepts with displays translated to Canadian French.

- code: 2-6
  system: http://loinc.org
  language: fr-CA
  translation: Almécilline:Susceptibilité:Temps ponctuel:Isolat:Quantitatif:CLM
- code: 1-8
  system: http://loinc.org
  language: fr-CA
  translation: 'Acyclovir:Susceptibilité:Temps ponctuel:Isolat:Quantitatif ou ordinal:'

More details

See also: Hybrid Terminology Engine.