Multiple Language Support| Hitchhikers Platform

Overview

Pages provides first-class support for deploying sites in multiple languages. Knowledge Graph language profiles and streams localization are the mechanisms that facilitate multi-language support.

Before implementing a multi-language site, you should have completed/be comfortable with the following material:

  1. Language Profiles in Knowledge Graph
  2. Pages Multi-Language Support
  3. Knowledge Graph Saved Filters

This document will provide details on important implementation specifics that will ensure you can successfully implement a multi-language site.


Saved Filters and Language Profiles

A best practice for Pages implementations is to use saved filters, which allow you to define the set of entities to generate pages for. For example, each entity in the Knowledge Graph has a boolean field called Is Closed, which indicates whether or not an entity is currently in operation. A common Pages saved filter checks that this field is equal to false; passing this saved filter to the stream in your TemplateConfig ensures you will only generate a page for entities that are actually “open”.

We recommend that your saved filters also check to ensure the Slug field is populated. This field is required for local development features, and is extremely useful for ensuring your page URLs are URL-safe!

The Knowledge Graph enforces saved filter logic at the level of the primary language profile. For multi-lang implementations, this fact is particularly important for the slug field, which can be used to build URLs. Since filter logic only applies to the primary profile, any saved filters which check for undefined slug fields may return non-primary profiles for which the slug field is not populated.

light bulb
Tip
You MUST ensure that all deployed Pages have sufficient information in the Knowledge Graph across all language profiles, so they are rendered properly on deploy. If your slug is null for alternate language profiles, the page will still be available, even if the information is incomplete. If you’re not ready to deploy an alternate language page for an entity, delete the alternate language profile.

Example

Let’s say you have English as the primary language profile and Spanish as a secondary language profile for a set of location entities in your Knowledge Graph. The slug field for all of the English profiles is populated with the following format:

[[localeCode]]/[[entityId]]

The Spanish profiles do not have any value populated for the slug. In this case, a saved filter that filters out undefined slugs would return Spanish profiles with undefined slugs because the filter logic is applied to the primary language profile, which satisfies the filter criteria.

The undefined slug would cause a failed deploy because of URL collision errors, i.e. multiple pages served at .../undefined.

As always, good programming dictates setting up sensible defaults. In this case, a check for an undefined slug in the getPath function will do the trick:

export const getPath: GetPath<TemplateProps> = ({ document }) => {
  return document.slug ? document.slug : `${document.locale}/${document.address.region}/${document.address.city}/${document.address.address1}-${document.id.toString()}`;
};

The above getPath uses the recommended pattern of building the URL from the slug, but provides a sensible default in the case where the slug is undefined.

Importantly, the fall back value in the case where slug is undefined is guaranteed to be unique because it uses the document ID. This will ensure that a deploy will not fail due to URL collision errors if the slug is not defined.


When accessing values from related entities in your stream configuration, it is important to remember that the stream will only return values for the language profile you have selected.

For example, if a page for a financial advisor in English references related financial advisors, the stream will only provide information for the related entities from the English profile.

Advisor A has profiles in :

  • Spanish
  • English

Advisor B has a profile in:

  • English

In order for the Spanish page for Advisor A to link to the English page of Advisor B, the following configuration must be used:

  • Advisor B must have a Spanish profile, which will likely be empty, since Advisor B cannot speak Spanish.
    • Note: Only Spanish profiles will be accessible on Advisor A’s Spanish page.
    • For Advisor B’s Spanish profile, we recommend an empty profile or information in Spanish informing the user that this advisor only works in English and redirects the user to the English language page for Advisor B.
  • Slug field on Advisor B Spanish profile must be set to overridable and revert to the English language slug field.
    • If you need a refresher on overridable field values, check out this unit on Field Behavior.

multi-lang-diagram.png

light bulb
Tip
Some regulations require that the page language matches its language description, i.e. a Spanish page contains Spanish text and not English text. Be sure that your Pages have the appropriate match between language description and content. While we recommend you maintain content in the Knowledge Graph, in cases where manual translation of hard-coded strings is required, we recommend using the i18n library.
Feedback