Strapi internationalization for multilingual content

In Strapi 5, one piece of content is a document with a shared identity, and each locale is a version of that document rather than a separate entry. The Document Service API is the layer that reads and writes these documents, and it replaced the Entity Service API used in v4. For planning, this matters because a French article and its English original are linked records under one document, not two unrelated entries. Teams that build front-end routes, search indexes or integration jobs should understand this link before writing any fetch logic, since it determines how they find the translation of a given item and how they detect that a translation is missing.

When a locale is added to a localized content type, the key question is what happens to documents that already exist. Strapi creates locale variants so the new language can be filled in, but the exact behavior, including whether variants appear immediately for existing documents, whether localized fields start empty or are prefilled, and which roles can add locales, should be confirmed in the current Strapi 5 internationalization documentation for the version you run. Plan a test on a staging instance: create a document before adding the locale, add the locale, and check what editors see in the admin panel and what the API returns for the new locale.

Fields that are not localized behave differently. A non-localized field holds one value that every locale shares, so changing it while editing one locale changes it for all of them. This suits identifiers, slugs that must stay stable across languages, prices, dates and media that does not need adaptation. Copy such as titles, summaries and body text should stay localized. Decide this per field before content goes live, because changing a field's localization setting after content exists can affect the values already stored, and the migration behavior for that change should be checked in the docs and on a copy of your data first.

Verify the model with a short test matrix before editors start work. Create a document in the default locale, add a second locale, change a localized field in each locale, change a non-localized field in one locale and confirm it appears in the other, then publish one locale and confirm the other is unaffected. Repeat the same checks through the API with the locale parameter your front end will use. Strapi 5 minor releases have shipped roughly weekly, so retest after each upgrade, and treat the official Strapi 5 i18n documentation for your exact version as the reference for storage and behavior details.

The front end decides which language a visitor sees, so the locale must be passed on every content request rather than assumed by the server. In Strapi 5, REST requests select a language with a locale parameter in the query string, and GraphQL requests pass the same choice as a locale argument on the collection or single-type field. Your front end should resolve the visitor's language once, from the URL path, a cookie or the Accept-Language header, then use that single value for every call on the page. Mixing locales within one page render is a common source of content that looks translated but is not.

Missing translations need an explicit rule. When a document has no entry in the requested locale, Strapi returns no content for that locale, so the front end must decide whether to show the default locale's entry, hide the item or display a notice. Strapi does not perform the fallback for you across every query shape, so confirm in the current docs how a request behaves when the locale is absent, and whether your chosen approach works for single types, collections and nested relations. Decide the fallback chain (for example, requested locale, then default locale) before building components, and write it down so editors know which fields will appear in the wrong language.

Populated relations need the same care. A related entry, component or media item may exist only in the default locale, and population settings determine whether the related item is returned in the requested locale at all. Test a page that pulls a linked article, a repeatable component and an image, in a language where some of those pieces are not yet translated. Confirm the exact populate syntax for your Strapi 5 version in the current documentation and in a test build of your front end, because query parameter names and nesting rules have changed between major versions and are easy to get subtly wrong.

Strapi 5 also changes the response shape compared with v4. Entries are returned flatter, with attributes at the top level of each object instead of nested under an attributes key, and the Document Service API replaces the Entity Service API behind the scenes. Front-end code that reads locale or translation data from the v4 structure will break or silently return undefined values. The Strapi-Response-Format: v4 header exists for backward compatibility during migration, and it is a useful aid while you move an existing front end across. Treat it as a temporary bridge, not a target format, and remove it once your parsers handle the Strapi 5 shape.

Before go-live, run a small checklist with your front-end team: request each page in every enabled locale, remove a translation on purpose and confirm the fallback behavior, and check that the language code in the URL, the locale parameter and the lang attribute on the page all agree. Record the results against the Strapi version you deploy, since minor releases ship frequently. Ask your implementation partner, or your own team, to include these cases in the test plan so that a locale mismatch is caught before editors and visitors find it.

The first decision is where translation work happens. Strapi's free i18n feature gives translators a locale switcher in the admin panel, so a translator can open an entry, pick a target locale and fill in the localized fields of that entry. For a small team with a few locales and simple copy, that may be the whole workflow. For larger programs, many teams keep drafting and translation in an external process, such as a translation management system or a spreadsheet-based queue, and then write the results back into Strapi. Decide this before you configure locales, because it determines who needs admin accounts, which roles can edit which locales, and how you will know a translation is missing. Start by naming who creates the source content. In a typical setup, editors in the default locale write and publish the source entries, and translators work only on the other locales. Make that split explicit in the Users and Permissions and admin role settings so that translators can edit localized versions without changing the source language. Also decide whether a translated entry can be created from a source entry automatically when a new locale is added, or whether translators start from a blank localized version. The second option produces more gaps, which is why the tracking step below matters. Review is the second decision. Strapi's Review Workflows, which add stages such as a required approval before publishing, are an Enterprise feature, so do not design the process around them unless your plan includes them. On a Community or Growth plan, you must decide whether a second person checks each translation before publication by an agreed convention, such as a reviewer who edits the localized entry directly, or by a step in your external tool that gates the write back to Strapi. Confirm with your Strapi plan and your own process which of these you can enforce, and document who is responsible for each locale. Missing translations need a tracking method that does not depend on memory. Strapi shows locale variants of each entry, so an editor can see which locales exist for a document, but a site-wide report of untranslated fields is something you should plan yourself. Common approaches include a scheduled query against the API that compares locales per document, a filtered list in the admin panel reviewed by the content lead, or a status field in the content type that translators update. Test whether your front end falls back to the default locale when a field is empty, because that behavior decides whether a gap is visible to readers or hidden. Finally, decide whether approval happens inside Strapi or outside it. Approve inside Strapi when the editor who publishes is also the person who signs off, the team is small and the audit needs are modest. Approve outside when translations come from a vendor or a language review board that works in its own tools, and let Strapi receive only final content. Coordinated publishing of several locales together is handled by Strapi Releases, covered on the releases page, and audit trails for who changed what are an Enterprise feature covered elsewhere on this site. Write the decision down per content type, since a marketing page and a legal notice often need different approval paths.