Internationalization

Internationalization with TinaCMS

Managing multilingual content is essential for global reach. TinaCMS provides versatile options to facilitate this. This guide focuses on two main strategies:

  • Directory-Based Localization
  • Field-Based Localization

Directory-Based Localization

With directory-based localization, your content should be structured in a directory-based manner, where the locale (e.g., en, fr) lives underneath the collection root (e.g., blog, docs). For example:

blog
en
hello-world.md
fr
hello-world.md
docs
en
my-doc.md
fr
my-doc.md

Steps to Implement Directory-Based Localization

In your config.ts, you likely will have one collection that contains all your locales

Routing and File Structure:

Whether you're using Next.js, or another framework, your routing logic should be updated to pick the correct locale based on either the URL or user setting.

Using the locale, you can filter for document(s) based on the path

For more info on setting up the routing for NextJS-specific implementations, see our guide

Content Management

With this setup, editors will browse locales for each collection via the document list.

If a user wants to create a new localized version of an existing document, they can click "duplicate document" from the document list, and prepend the desired locale in the new document's filename.

Field-Based Localization

In this approach, each localized field contains nested values for multiple languages. For example, a single Markdown file might look like this:

Steps to Implement Field-Based Localization

You will need to modify your TinaCMS schema to include localized fields.

If you are using markdown/mdx content, and want to use the markdown body for your content, you might prefer using the directory-based approach to localization.

Display Localized Content:

In your site's components, you can then choose the correct localized field to display based on the current locale.

Content Management:

TinaCMS will display all localized fields as children of the root-level field.

Internationalization with GitHub Action

When using Directory-Based Localization, developers need to place the corresponding language MDX or JSON files in the correct location for loading multilingual routes. Developers can choose to manually translate text content and place it in the correct location, or they can use a GitHub Action to automate this process. The following is an example explaining the workflow of an effective GitHub Action:

View the GitHub Action workflow steps

Last Edited: July 11, 2025