Internationalization

Internationalization is the process of designing a software application so that it can be adapted to various languages without code changes. The API provides some features available to developers that want to support internationalization. These features allow partners to make requests in a language other than English. This guide will explain how to use the internationalization features of the FamilySearch API to provide support for new languages.

Why Internationalization?

Users will want to see information from FamilySearch displayed in their own language. For example, a Spanish-speaking user will want to see the Spanish word for "Deceased" for a person in the Tree. Various languages are provided by the API based on a specific endpoint. By specifying the lang and the locale tags, you can determine which language the user will see.

How to request a different language

Clients can request a different language using the Accept-Language header according to HTTP specifications. FamilySearch also supports passing in the locale query parameter for convenience. This parameter is discouraged, however, and the Accept-Language header is preferred.

What data can currently be internationalized?

The FamilySearch API provides several different resources that support Internationalization. The Places, Controlled Vocabulary, and Dates resources will return localized values. The Persons resource also supports internationalization but only the display properties will be localized according to the Accept-Language header.

• Persons resource
  • Only display properties are localized
• Places resource
  • Name properties are localized as well as place names, place type names and descriptions, type and description group names and descriptions.
• Controlled Vocabulary resource
  • Values of the terms, whether in a list or a single query, will be localized
• Dates resource
  • Display value of the date is localized

Example Requests

Request

GET /platform/tree/persons/L61X-YCS
Accept: application/x-gedcomx-v1+xml
Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Response

  ...
        <nameForm lang="en">
                <fullText>Maria Petra VALDEZ</fullText>
                <part type="http://gedcomx.org/Given" value="Maria Petra"/>
                <part type="http://gedcomx.org/Surname" value="VALDEZ"/>
        </nameForm>
        <nameForm lang="es">
                <fullText>Maria Petra VALDEZ</fullText>
                <part type="http://gedcomx.org/Given" value="Maria Petra"/>
                <part type="http://gedcomx.org/Surname" value="VALDEZ"/>
        </nameForm>
  ...
        <display>
            <birthDate>1 March 1884</birthDate>
            <birthPlace>Cosoleacaque, Veracruz, Mexico</birthPlace>
            <gender>Female</gender>
            <lifespan>1884-Deceased</lifespan>
            <name>Maria Petra VALDEZ</name>
        </display>
  ...

The response with the Accept-Language header set to Spanish. Note that the nameForm property doesn't change.

Request

GET /platform/tree/persons/L61X-YCS
Accept: application/x-gedcomx-v1+xml
Accept-Language: es
Authorization: Bearer YOUR_ACCESS_TOKEN_HERE

Response

 ...  
        <nameForm lang="en">
                <fullText>Maria Petra VALDEZ</fullText>
                <part type="http://gedcomx.org/Given" value="Maria Petra"/>
                <part type="http://gedcomx.org/Surname" value="VALDEZ"/>
        </nameForm>
        <nameForm lang="es">
                <fullText>Maria Petra VALDEZ</fullText>
                <part type="http://gedcomx.org/Given" value="Maria Petra"/>
                <part type="http://gedcomx.org/Surname" value="VALDEZ"/>
        </nameForm>
  ...
        <display>
            <birthDate>1 marzo 1884</birthDate>
            <birthPlace>Cosoleacaque, Veracruz, México</birthPlace>
            <gender>Femenino</gender>
            <lifespan>1884-Fallecido(a)</lifespan>
            <name>Maria Petra VALDEZ</name>
        </display>
  ...