Manage multi-lingual content

9 min

Global applications require strong multilingual support. Optimizely Graph offers features that help deliver seamless international experiences, including language-optimized storage, intelligent fallback mechanisms, and natural language processing.

Multi-language content ensures users receive information in their preferred language. It improves search relevance, supports cultural accuracy, and boosts engagement across regions.

Multilingual content support in Optimizely Graph

Optimizely Graph stores each language version in language-optimized storage with specialized search algorithms for different languages. This approach ensures the following:

Optimized performance for language-specific text analysis and searching.

Accurate tokenization and stemming tailored to each language's linguistic characteristics.

Cultural and linguistic precision in search results and content ranking.

Automatic fallback handling when content is unavailable in the requested languages.

By default, GraphQL queries return content from all available languages unless the content is explicitly filtered. This provides maximum content coverage but may require client-side language filtering.

Key components to manage multilingual content

Send multilingual content to Graph – Configure and sync multi-language content in Optimizely Graph, including language-specific indexing and fallback relationships.

Query a specific locale – Query content in specific languages using GraphQL, supporting single, multiple, and user-preferred language queries with automatic fallback.

Use natural language processingUse natural language processing – Enhance search accuracy through language-specific natural language processing and semantic search within language contexts.

Use fallback languagesUse fallback languages – When content is unavailable in the requested language, Optimizely Graph uses fallback logic to return the next best match. This ensures users always see relevant content and avoids broken experiences.

Multi-lingual search

Optimizely Graph supports language-specific and cross-language search. Tailor search behavior based on user preferences and content availability.

Language-specific search

Use this query to search within specific languages. It applies semantic ranking and ensures results are linguistically relevant.

query SearchInSpecificLanguage($searchTerm: String!, $locale: [Locales]!) {
  Content(
    where: {
      _fulltext: { match: $searchTerm }
    }
    locale: $locale
    orderBy: { _ranking: SEMANTIC }
  ) {
    items {
      Name
      _score
      Language {
        Name
      }
      _typeName
    }
  }
}

Cross-language search

Use this query to search across all available languages. It is useful when you want to maximize content coverage regardless of locale.

query SearchAcrossLanguages($searchTerm: String!) {
  Content(
    where: {
      _fulltext: { match: $searchTerm }
    }
    orderBy: { _ranking: RELEVANCE }
  ) {
    items {
      Name
      _score
      Language {
        Name
        DisplayName
      }
      _typeName
    }
    total
  }
}

Best practices and limitations

Performance best practices

Use only the languages you need – Target a specific language for a single-page article to improve performance and reduce unnecessary data:

# Good: Specific language for single-page content
query GetSpecificArticle($locale: [Locales]!) {
  ArticlePage(locale: $locale, limit: 1) {
    items { Name }
  }
}

Request one language when only one is needed – Retrieve the English version of an article when multilingual results are unnecessary:

# Optimal for getting one specific language version
query GetEnglishVersion {
  ArticlePage(locale: [en], limit: 1) {
    items { Name, TeaserText }
  }
}

Avoid querying all languages unless necessary – Requesting all locales increases load and complexity. Use it only when multilingual output is required.

Common patterns

Website language switcher – Retrieve a page in all available languages to build a language switcher user interface (UI):

query GetPageInAllLanguages($relativePath: String!) {
  Content(
    where: {
      RelativePath: { eq: $relativePath }
    }
  ) {
    items {
      Name
      RelativePath
      Language {
        Name
        DisplayName
      }
    }
  }
}

Language-filtered content lists – Return a list of articles filtered by the user's preferred locale, ordered by publish date:

query GetLocalizedArticles($userLocale: [Locales]!, $limit: Int = 10) {
  ArticlePage(
    locale: $userLocale
    orderBy: { StartPublish: DESC }
    limit: $limit
  ) {
    items {
      Name
      TeaserText
      StartPublish
      RelativePath
      Language {
        Name
      }
    }
  }
}

Implementation tips

Client-side language detection – Use browser language preferences to set the default locale.

URL-based language routing – Map URL segments to locale parameters.

Fallback handling – Handle cases where content might not exist in the requested language.

Performance monitoring – Monitor query performance when using multiple locales.

Considerations

Query efficiency – Querying multiple languages increases result set size and processing time.

Content availability – Not all content may be available in all languages; handle missing translations carefully.

Search relevance – Language-specific search algorithms may return different relevance scores across languages.

Caching strategy – Consider language-specific caching strategies for better performance.