Advanced Multi-Lang Support | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to provide alternative language text
• Best practices for translating hardcoded text

Alternate Language Fields

The stream config also supports an alternateLanguageFields array, which allows the user to access entity fields from any language profile. For example, if you wanted to use the Spanish language name on an English page, you could access the Spanish name by using the alternateLanguageFields array.

export const config: TemplateConfig = {
  stream: {
    $id: "my-stream-id-1",
    fields: [
      "id",
      "uid",
      "meta",
      "name",
      "description"
    ],
    filter: {
      entityTypes: ["location"]
    },
    localization: {
      // We are including "es" in the locales array to generate a Spanish page for every location
      locales: ["en", "es"],
      primary: false,
    },
  },
	// We can now access the name field on any other entity profiles
  alternateLanguageFields: [
    "name",
  ]
};

Examining the localData directory for an English-language entity, we observe that the Spanish-language name is available for use in the template:

"alternateLanguageFields": {
  "es": {
    "name": "Restaurante Turtlehead Tacos"
  }
},

In the simple template below, we can display both the English and Spanish language names. The ability to access alternative language profiles allows for a rich multi-language experience for users, who might desire multiple language options. For example, safety instructions may need to be listed next to each other in multiple language, and the alternateLanguageFields enables easy access to the multi-lang profile data.

const Location: Template<TemplateRenderProps> = ({
  document,
}) => {
  const {
    name,
    alternateLanguageFields,
    locale
  } = document;

  return (
    <>
      {locale === "en" ?
        <div>
          Alternate Language Name: {alternateLanguageFields.es.name}
        </div>
        :
        <div>
          Alternate Language Name: {alternateLanguageFields.en.name}
        </div>
      }
      <div>
        Primary Language Name: {name}
      </div>
    </>
  );
};

export default Location;

Note the use of the ternary operator in the return statement. This is necessary because attempting to access alternateLanguageFields.es when the locale is “es” will throw a generation error because “es” will be undefined.

When using alternateLanguageFields make sure you have accounted for possible null values to dereferencing an undefined field.

Translating Hardcoded Strings in Templates

When supporting multi-lang templates, the recommended best-practice is to pull as much content as possible from the Knowledge Graph and minimize hardcoded strings in the template.

By avoiding hardcoded strings, you can leverage all the power of Knowledge Graph language profiles to generate language-agnostic templates.

Nonetheless, there may be times when you must include hardcoded strings in your template, but still require translation. We recommend using the i18next internationalization framework, which integrates well with a React-based Pages application.

We recommend the following tutorials for integrating i18next into a React application:

1. i18next Documentation
2. How to properly internationalize a React application using i18next

While third-party tools like i18next that support translation integrate well with Pages, we strongly recommend parameterizing your Knowledge Graph templates with stream-based data. Doing so will speed up your development process and allow for easier content management through the in-build Knowledge Graph and Streams system.