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.

Only two steps are required to implement basic multi-language support:

1. Set up language profiles for Knowledge Graph entities
2. Configure Streams to accept multiple locales

By decoupling content (stored in KG language profiles) from template logic (configured in Streams), you can generate language-specific pages without writing language-specific code. Once your stream is correctly configured, PagesJS will generate a unique page for each language profile automatically.

Knowledge Graph Language Profiles

Knowledge Graph entities support language profiles, which allow you to set up language-specific field values. For example, a location entity with both English and Spanish profiles could store its description in both languages. You can think of a language profile as a separate view into an entity, where certain fields have language-specific values.

Note: Some fields do not support language-specific content, such as Entity ID and Map Marker, because these fields shouldn't vary by language profile. 

Step 1: Configure Language Profiles in the Knowledge Graph

Enable the Account Feature

To start adding language profiles to your entities, first turn on the account feature called "Multi-Language Profiles" in your account.

Create an Alternate Language Profile

Once the feature is enabled, add alternate language profiles to your entities:

1. Navigate to Knowledge Graph > Entities, and click your entity type (e.g., "Location") in the left sidebar to filter.
2. Click the checkbox in the top left of the entity results table to select all entities.
3. Under the More Actions dropdown, select Edit.
4. Add the desired language as an Alternate Language Profile.

Edit Content on an Alternate Language Profile

Once language profiles are set up, you can start editing fields with language-specific content. When you select an entity or set of entities to edit, click on the relevant language in the sidebar.

When a profile is selected (e.g., Spanish), all edits you make will only apply to that language profile; other profiles remain untouched.

Configure Slugs for Multi-Language URLs

One key component of multi-language profiles is managing localized URLs through the Knowledge Graph. For each entity powered on Pages, you will see a built-in Slug field in the Knowledge Graph. This can be edited per language profile so you can store a localized URL.

Using slugs is the recommended practice for naming URL paths in Pages. You must configure slugs correctly to prevent URL collision errors when using multiple languages. We recommend this format:

[[localeCode]]/[[entityId]]

localeCode is an entity field containing a string representation of the currently selected language profile. By using double square brackets, you can reference other field values — this is called "embedding fields." See this tutorial for details.

With this format, Spanish slugs will look like /es/[[entityId]], prepending "es" to every Spanish page's URL to avoid collisions.

Bulk Edit Slugs and Name Field

To apply the same slug format to all entities in a given language profile:

1. From the Entity Edit screen (following the bulk edit steps above), ensure you have selected the target language profile (e.g., Spanish) in the Languages window on the right.
2. Click into the Slug field and type: [[localeCode]]/[[entityId]]

3. Click Save for [X] profiles. Every entity in that language profile will now have the correctly formatted slug.

   

4. Optionally, update the Name field with a translated value (e.g., "Restaurante Turtlehead Tacos") and save.

You can also edit individual entities to add unique, entity-specific content in the alternate language. When editing an entity, switch between language profiles in the sidebar to view and edit the field values for each.

Step 2: Configure Your Stream

To access language profile data in your Pages templates, add the desired locales to the localization object in your stream config:

export const config: TemplateConfig = {
  stream: {
    $id: "my-stream-id-1",
    fields: [
      "id",
      "uid",
      "meta",
      "name",
      "address",
      "mainPhone",
      "description",
      "hours",
      "slug",
      "geocodedCoordinate",
      "services",
    ],
    filter: {
      entityTypes: ["location"]
    },
    localization: {
      // Include "es" in the locales array to generate a Spanish page for every location entity
      locales: ["en", "es"]
    },
  }
};

By adding "es" to the locales array, Pages will generate a Spanish language page for each location entity that has a Spanish profile. To support additional languages in the future, simply add the appropriate localeCode to the array.

Note: primary must be false when you have more than one locale.

Best practice: Rather than filtering by entity type alone, use a saved filter to ensure all generated entities meet certain criteria — for example, checking that Is Closed is false and that the Slug field is populated. 

Step 3: Configure getPath

Set up your getPath function to use the slug field configured in the Knowledge Graph:

export const getPath: GetPath<TemplateProps> = ({ document }) => {
  return document.slug;
};

Because the slug is already configured in the Knowledge Graph with the locale prefix (e.g., /es/[[entityId]]), returning document.slug is all that is needed. When you add additional language profiles in the future, no further changes are required here — just update the Knowledge Graph slugs and the locales array in your stream config.

For production robustness, we recommend a fallback in case the slug is undefined for any alternate language profile:

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 fallback builds a URL from fields guaranteed to be unique (using document.id), preventing URL collision errors if a slug is not defined for an alternate profile.

Saved Filters and Language Profiles

A best practice for Pages implementations is to use saved filters to define the set of entities to generate pages for. We recommend that saved filters check that the Slug field is populated, as this field is required for local development and is important for ensuring URL-safe paths.

However, there is an important consideration for multi-language implementations: the Knowledge Graph enforces saved filter logic at the level of the primary language profile only.

This means a saved filter that checks for a non-null slug may return non-primary language profiles for which the slug field is not yet populated — because the primary profile passes the filter, the alternate profiles are included regardless.

Example

Say you have English as the primary profile and Spanish as a secondary profile for a set of location entities. The English profiles all have slugs in the format [[localeCode]]/[[entityId]]. The Spanish profiles have no slug value set. A saved filter checking for a non-null slug would still return the Spanish profiles, because the filter is evaluated against the English (primary) profile.

An undefined slug would cause a failed deploy due to URL collision errors (multiple pages served at .../undefined).

Note: You must ensure that all deployed pages have sufficient information in the Knowledge Graph across all language profiles so they render properly. If a slug is null for an alternate language profile, 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.

The getPath fallback shown above handles this case by constructing a guaranteed-unique URL when document.slug is undefined.

Related Entities and Language Profiles

When accessing values from related entities in your stream configuration, the stream will only return values for the language profile you have selected. This is an important consideration when building pages that reference related entities.

For example, consider a financial advisor site where Advisor A has profiles in both English and Spanish, but Advisor B only has an English profile. In order for Advisor A's Spanish page to link to Advisor B, the following configuration is needed:

• Advisor B must have a Spanish profile (which may be empty, or contain a note redirecting Spanish-speaking users to the English page).
• The Slug field on Advisor B's Spanish profile must be set to overridable, reverting to the English language slug field so the link can resolve correctly.

If you need a refresher on overridable field values, check out the unit on Field Behavior.

Note: Some regulations require that the page language matches its content language (e.g., a Spanish page must contain Spanish text, not English). Be sure your pages have the appropriate match. While we recommend maintaining content in the Knowledge Graph, in cases where manual translation of hard-coded strings is required, we recommend using the i18next library.

Local Development

There are two methods for testing multi-language pages locally.

Development Mode (npm run dev)

Standard local development mode. By default, this displays English (en) pages. To preview a page in another language, append the ?locale=[localeCode] query parameter to your URLs.

For example, to preview a French page at http://localhost:5173/location/xxxxxxxxx:

http://localhost:5173/location/xxxxxxxxx?locale=fr

This works well for editing template structure, but does not reflect production URL paths.

Production Build (yext pages develop)

To test URL structure exactly as it will appear in production, use the production build workflow. Run the following commands in order:

1. yext pages generate — Build and generate the required pages for local testing.
2. yext pages generate-test-data — Pull test data from the Knowledge Graph into the localData folder.
   • To generate test data only for a specific language, run: yext pages generate-test-data --locale es
3. yext pages serve — Serve your site locally at localhost:8000.

To see which pages are available locally, navigate to localhost:8000/s or any page that returns a 404. This takes you to the Yext Development Page, where you can see all locally available pages:

Note: When you pull local data from your Knowledge Graph, only a subset of entities will be available on your local machine.

Translating Hardcoded Strings in Templates

The recommended best practice for multi-language templates is to pull as much content as possible from Knowledge Graph entities and minimize hardcoded strings. By avoiding hardcoded strings, you can leverage the full power of Knowledge Graph language profiles to generate language-agnostic templates.

When you must include hardcoded strings that require translation, we recommend the i18next internationalization framework, which integrates well with a React-based Pages application:

• i18next Documentation
• How to properly internationalize a React application using i18next

While i18next integrates well with Pages, we strongly recommend parameterizing your templates with stream-based data wherever possible, as it speeds up development and allows for easier content management through the Knowledge Graph and Streams system.