Directus content translations work through relationships between shared records, language records and translated fields. This Directus multilingual guide explains the built-in Generate Translations workflow, the languages collection, translation junction collections, the translations interface, API retrieval, access policies and international SEO. It is for editors and developers who want readers in different countries to find accurate localized information without changing shared data.
To translate Directus content professionally, choose the fields that need local language versions and create the associated translation infrastructure. Current Directus documentation describes a wizard that can generate the languages collection, a collection-specific translations junction and the relational alias, while manual modeling is also possible. The resulting interface is convenient for editors, but the public application still needs to request the correct related language record and enforce read permissions that do not expose drafts or private information.
Quick guide: inspect the shared collection; mark which fields are translatable; create or verify the languages and junction collections; confirm the relation and language keys; enter approved translations by language; protect shared identifiers and permissions; fetch the intended related records through the API; test missing translations and right-to-left content; verify website routes, metadata and linked destinations; release one complete journey and retain evidence of the actual result.
Quick answer: translation must survive the whole publishing path
The useful question is not simply whether Directus can store another language. It is whether a reader who opens the target route receives the intended version of every important instruction, follows correct links, and understands what action is available. Begin with a small set of entries, one target locale and a written expected result. Recreate the journey after each change rather than guessing from an editing screen.
Translation should protect facts as well as fluency. Keep record identifiers, dates, prices, measured values, legal conditions and source references attached to their actual owners. Give translated prose enough space to be natural, but do not invent permissions, guarantees or benefits. Where the underlying facts differ by market, document that as an approved localized content decision, not an accidental consequence of translation.
Definition lock: the essential concepts and their boundaries
Directus uses a relational data model rather than assuming a translation is a second independent copy of the entire business record. The source collection can keep shared fields, and a related translations collection can carry language-specific text. The translations alias is a relational editing interface, not itself a regular database column containing the translated article. Readers do not interact with that interface; they interact with an API and a frontend whose language selection, permissions, SEO and fallback behavior must be designed separately.
For this guide, a locale is a configured language or language-region selection; a translation is approved content intended to preserve the source’s relevant meaning for that audience; a fallback is a defined substitute when a requested value is unavailable; and a published result is what a permitted external reader can actually obtain. These words describe different decisions. A fallback may be technically permitted but editorially unsuitable. A published record may exist without a valid route. A fluent translation may still contain an incorrect factual condition.
One realistic example to carry through the guide
Use a global public transport guide as the example. Its stable station identifier and coordinates are shared; station descriptions, accessibility instructions, titles and help text may vary by language. English, Spanish and Arabic versions should describe the same station accurately, with the Arabic layout tested for text direction. A missing translation must not cause a station to be mistaken for another location or an accessibility condition to disappear.
A practical vocabulary before you start
- Languages collection
- Translations junction
- One-to-many alias
- Language code
- Shared parent record
- Access policy
- API deep filter
- Right-to-left direction
Do not memorize these terms as isolated labels. For every one, identify its corresponding item in your own project. Ask who owns it, where it is configured, what could go wrong, and how to confirm the result from outside the editor. A glossary becomes genuinely useful when it connects words to observable behavior.
Twenty detailed lessons for Directus multilingual publishing
1. Inspect the parent collection first
A Directus collection often contains shared attributes that should be preserved while descriptive fields vary by language.
A translation project becomes easier when it defines the complete reader task rather than a vague quantity of words. List the actions a visitor must complete, the decisions that depend on the text, and the consequences of a misunderstanding. This makes priorities visible: an inaccurate eligibility rule is more urgent than an awkward decorative headline. A usable scope names the content owner, language reviewer, developer, release environment, and the place where a reader will see the result.
What can go wrong: Editors attempt to duplicate an entire station record for every language and create inconsistent coordinates. Look at the real reader’s first decision before tuning the text. A sentence can be grammatical yet leave someone uncertain about what happens next. Read the source and target in context, ask what choice each permits, and note any new promise that appears only in translation. When an essential qualification is absent, pause publication and resolve it with the person who owns the underlying rule.
What to do: Mark stable identity and operational facts before enabling content translations. Start with a deliberately small specimen that contains ordinary prose, a link, a conditional instruction, and a visible call to action. Walk through its origin, stored representation, API or template, and final rendering. Write down which layer is responsible at each stage. If the same words appear on another page, identify whether they are shared content or a copied entry. You want a reproducible map before scaling the number of target-language items.
Acceptance evidence: One station keeps one underlying identity across all supported languages. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
2. Use the Generate Translations wizard
Current Directus documentation describes a content-translation wizard within collection settings.
Locale codes are routing and data-selection keys, not decorative flags. The project may distinguish a language from a market, and may also maintain region-specific variants. The distinction matters when two audiences use similar vocabulary but different conventions for dates, formal address, units, or legal statements. Build a locale inventory with the exact codes supported by the configured system and by the application consuming it. Do not assume that a label in an editing interface establishes the language of the public page.
What can go wrong: A team manually builds a complicated relation that the built-in setup could have generated. Keep locale selection visible during investigation. If a test passes only while logged in as an editor, repeat it in a public or appropriately restricted client. Compare the requested language, returned language, and displayed language; they should not be inferred from one another. Record the full path from request to rendered phrase rather than a screenshot without context.
What to do: Inspect the wizard’s chosen fields and generated objects in a safe test collection. Document a source locale, the intended target, regional variants, default behavior, and the list of markets where each variant may appear. Have someone test the exact code through the delivery route rather than accepting a country dropdown as proof. Try a language the site does not support and record the expected safe result. A project that cannot describe its own locale matrix will struggle to diagnose apparently random translation errors.
Acceptance evidence: A languages collection, junction collection and translations alias exist as intended. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
3. Understand the languages collection
The languages collection identifies supported language codes and can record language direction.
Structured content has two kinds of information: facts that should remain the same everywhere, and presentation or explanation that must change for a particular audience. A product identifier, event timestamp, membership entitlement, or database relationship often belongs to the first category. A title, introduction, instruction, text alternative, or locally approved claim may belong to the second. Translating a shared identifier can create two apparent objects where only one should exist.
What can go wrong: A developer treats translated language names as reliable foreign keys instead of stable codes. Ask whether a proposed translation changes a value, a label, or an identity. Human-readable labels can change; keys and relationships often cannot. When the wrong field has been edited, restore the original data first and then place the localized wording where the model expects it. Documentation should identify this boundary for every editor who touches the record.
What to do: Use configured codes consistently and preserve direction information when relevant. For each field, assign one of three treatments: shared and immutable, localized with a named owner, or conditionally localized under market rules. Record why the treatment was chosen. If a value is shared but looks like prose, consider whether it is actually an internal key. If a value is localized but carries a business fact, require the fact owner to review the target version. This prevents both accidental divergence and unhelpfully literal copy.
Acceptance evidence: Spanish and Arabic are resolved by their exact language identifiers. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
4. Keep translatable fields in the junction
The translations collection contains language-dependent fields related back to a shared parent item.
The notion of one article or item can become complicated when multiple language versions exist. Editors need to know which translated records belong together, which identifier survives a language switch, and how a new revision is tied to its source. A missing or duplicated relationship can send a reader to an unrelated page even if every sentence has been translated beautifully. Translation identity is a content-model property as much as a linguistic property.
What can go wrong: An editor adds title_english and title_spanish to the parent, making each new language a schema change. Test the relationship in both directions. Switching from the source to the target should reach the intended item; switching back should not create a duplicate or lose the reader’s place. Broken reverse navigation usually points to an identity or relation problem. Fix the mapping centrally and verify several specimens before relying on special-case redirects.
What to do: Use the chosen relational translation model for fields that should expand by locale. Draw a small relationship graph with one source item and two target versions. Include their identifiers, states, slugs, and the shared business object. Simulate a source update and ask how the target versions are flagged for review. Then simulate the deletion or unpublication of a translation. The expected action should be explicit, not inferred from the visible title. This diagram often reveals problems before the first API request is written.
Acceptance evidence: Adding a language does not require duplicating the whole parent object. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
5. Verify alias and foreign-key relationships
The translations interface uses an alias field backed by a relation to translated records.
Field-level decisions influence both editorial usability and technical complexity. A single field may contain a short label, a long explanation, or an entire rich-text document. Those formats require different checks for length, links, headings, embedded references, and translation context. More locale fields do not automatically mean better localization; excessive duplication raises maintenance cost. Equally, forcing all languages into one field can make independent review and publication impossible.
What can go wrong: A copied translation row points to a different station because the parent relation was incorrect. Remember that the reader is not looking at a data model. They see a button, paragraph, photograph or route, often on a narrow screen. Translation quality therefore includes clarity, sensible line breaks, accessible labels, and the preservation of necessary qualifiers. A shorter target is not automatically better; a longer target is not automatically worse.
What to do: Inspect parent key, translation key and language relation as a complete chain. Make a field inventory using real examples instead of an abstract schema. For a call-to-action button, check space and verb choice. For a warning, check scope and exceptions. For long-form text, check links, quotations, and heading structure. Separate the decisions about storage from decisions about editorial approval. A technically convenient representation is useful only when the team can reliably maintain and retrieve the right meaning.
Acceptance evidence: Every target text belongs to the intended source item. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
6. Prevent duplicate locale rows
The model should define what constitutes a unique translation for one parent and one language.
Relations create much of the usefulness of a structured website. Articles refer to authors and categories; products refer to variants; guides link to other guides. Some relations should stay shared, while others should select a language version. A localized title with a reference to the wrong-language destination can produce a seamless-looking but misleading reading experience. Translators should therefore understand links as claims about identity and context, not as punctuation around prose.
What can go wrong: A station displays two competing Spanish descriptions because duplicate language rows were allowed. Check the destination as carefully as the visible link. A related item might be unavailable in a target language, outdated, private, or contextually different. Decide whether readers should receive an explicit explanation, a permitted fallback, or no link. The chosen behavior should be stable across navigation menus, inline links, recommendations and search results.
What to do: Apply validation or database constraints appropriate to the deployment and review existing data. Choose a sample item with a parent, a related item, and a call-to-action destination. Record the expected destination for each supported locale. Test what happens when the related translation does not yet exist. A sensible system might retain a documented safe fallback or suppress the link, depending on the audience and risk. It should not silently send someone to a different subject. Link checks belong in the translation review, not only in engineering.
Acceptance evidence: At most the intended approved translation resolves for a given station and locale. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
7. Choose a missing-translation policy
Directus stores the related values; the frontend decides what to do when one locale has no row.
Fallback means a system supplies a value from another language or source when the requested one is missing. It is useful for continuity, but can conceal incomplete translation coverage. Fallback behavior may depend on whether the field is absent, empty, unpublished, or explicitly cleared. These states are not interchangeable. A page that looks complete at a glance can still contain a mixture of languages, particularly in rich text, metadata, error messages, or navigation.
What can go wrong: A station page shows English accessibility guidance beneath an Arabic heading with no explanation. Create a tiny matrix of present, missing, empty and withdrawn values. The same-looking blank space can represent a deliberate choice, an unavailable translation, a failed query, or an unpublished version. Test each state through the actual delivery path. Then give editors a way to see which policy was applied so that a fallback cannot disguise a critical omission.
What to do: State when fallback is allowed and how unavailable translation is signaled. Prepare four fixtures: translated text, missing field, intentionally blank field, and a withdrawn translation. Test all four in preview and in the publicly served content. Record the actual source of every rendered value. If fallback is allowed, define where it is acceptable and how editors discover it. If fallback is forbidden for legal notices or safety instructions, configure or enforce a publication gate. Treat fallback as a policy that must be explained, not a rescue mechanism that needs no oversight.
Acceptance evidence: Missing related language rows never silently change the claimed meaning. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
8. Review relational API responses
Translated content is reached through the parent record’s relationship and API field selection.
Rich text is not just a bag of words. Headings, annotations, hyperlinks, code fragments, embedded assets, and references carry meaning and sometimes behavior. A language model or translator may preserve the visible sentence but lose a linked condition or change the order of a list. When text is stored as structured blocks, the translation process should protect that structure while giving the language natural room to expand or contract.
What can go wrong: A client requests only the parent fields and concludes the Spanish translation is missing. Inspect structure as well as text. Where an element contains a link, list marker, citation or embedded reference, confirm both the translated explanation and the retained machine-readable relationship. A field can validate successfully while readers are sent to the wrong instruction. Include a keyboard and mobile check when the format is interactive.
What to do: Include the needed relation and apply a language filter using the documented API syntax. Use a test article containing a heading, an external link, an internal link, a quote, bold emphasis, and a numbered process. Compare the source and target at the structured-content level before opening the webpage. Then check the rendered page with a keyboard and screen reader where available. Verify that the link destination still matches the translated description. An intact JSON or block tree is necessary, but it is not enough: a structurally valid sentence can still communicate the wrong instruction.
Acceptance evidence: The response contains the intended target row and shared station data. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
9. Keep rich text, links and instruction order
Translated fields may contain formatted text and links that explain routes or accessibility.
Images, files, video captions, and text alternatives are part of a localized page. An image may be language-neutral, may contain embedded words, or may communicate a culturally specific example. A translated article with an untranslated diagram or missing caption is not fully understandable. Metadata such as alt text and download names may be stored separately from the main article, so an editor can easily miss them.
What can go wrong: An Arabic paragraph omits a condition about step-free access after formatting changes. Use one asset that contains visible wording and one that is language-neutral. Their proper treatment may differ. A language-neutral photograph can often be shared, but the alt text still needs review; a diagram containing words may require a separate localized version. Check the published file itself, not only the editor’s preview title.
What to do: Review meaning and rendered structure together, including the destination of every linked service. Classify each asset as reusable, language-specific, or in need of replacement. Check whether the system supports a localized asset field or requires a separate object. Confirm that a target page never shows the source-language accessibility description for a substantially different target-language image. In a demonstration, verify the actual file displayed, the caption, the alt description, the download label, and the link destination rather than checking only the asset record.
Acceptance evidence: The route instructions remain complete and actionable in each language. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
10. Localize media descriptions and downloads
A shared image may need different captions, alternative descriptions and attached guides in each target language.
The best workflow makes the unfinished state visible. Translation passes through preparation, assignment, drafting, review, approval, and release. Those states should not be confused with a content platform’s technical draft and publish toggles, which may have different meanings. A translated paragraph can be linguistically approved while its destination link is still unresolved. A reliable workflow therefore records both language quality and delivery readiness.
What can go wrong: A Spanish station guide links to an English PDF while promising Spanish instructions. Use a real handoff record. It should reveal which source text was reviewed, who approved the wording, what remains uncertain, and which page should be tested. A status such as ‘complete’ without those details gives false confidence. The record need not be bureaucratic: one clear page of evidence can prevent many hours of investigation.
What to do: Store translated descriptions in suitable related fields and label nonlocalized downloads honestly. Give each item a small status record: source version, target locale, translator, reviewer, outstanding questions, release approval, and last verified rendering. When the source changes, flag the target for review even if the platform itself still labels it published. Use explicit handoffs and one accountable final owner. Without that separation, teams often mistake the fact that a field was saved for the far stronger claim that readers can trust it.
Acceptance evidence: A reader can tell which language each asset uses and understands its purpose. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
11. Make translation entry usable for editors
The Directus interface can present translated values through language-oriented tabs or controls.
Changes in a source language create a subtle problem: an existing target translation may still be grammatical but no longer accurate. A policy can acquire one exception, a feature can change name, or a pricing condition can be narrowed. Automated systems often see these as strings, but readers experience them as promises. Translation maintenance must connect target approval to the exact meaning and version of the source.
What can go wrong: An editor saves Spanish wording under the wrong language due to an ambiguous tab label. Compare source revisions semantically. A changed adjective may be editorial; a changed condition about eligibility, safety or cost may require immediate target review. Highlight the changed meaning and ask the translator to revise the smallest complete unit that still makes sense. This is more efficient than blindly redoing every language after any edit.
What to do: Use understandable language indicators, ordering and review responsibilities. When a source entry changes, capture the changed fields and the reason. Classify changes as cosmetic, factual, instructional, or legally significant. Reopen only affected target content, but test the surrounding journey to make sure the revised wording does not conflict with older labels. Keep a changelog comprehensible to a translator rather than only a developer. This reduces rework and makes regressions traceable.
Acceptance evidence: Reviewers can inspect and correct the intended locale without altering neighbors. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
12. Differentiate shared and local approvals
A language editor may need rights to update a junction row but not shared station coordinates.
An API response is not the page a reader sees. It might expose the correct language while a frontend requests the default, caches an old item, or selects the first relation returned. Every technical translation guide must distinguish storage, retrieval, transformation, routing, and rendering. Different teams own those layers, so evidence must travel with the defect report. Otherwise each team can correctly say its own component works while the final experience remains wrong.
What can go wrong: A translator changes a parent field while intending only to revise a title. Use a controlled request and record its parameters. Verify the entry identifier, locale, selected fields, response status and whether the value is published. Only then examine the application output. Separating these checks makes a wrong-language page actionable: the team can name the layer that first produced the unexpected result.
What to do: Define the ownership and permissions of parent and translated collections separately. Test one entry by requesting the source locale, the target locale, and an unsupported locale in a controlled environment. Compare identifiers, field presence, and value origin. Then inspect the rendered route using the same entry. Capture timestamps, API parameters, response status, cache behavior, and the visible output. A documented example is more valuable than a generic claim that an endpoint is multilingual.
Acceptance evidence: A translator can edit approved language fields but not operational facts. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
13. Query related translations precisely
A public client may need nested relation fields and a filter for the requested language.
Selecting the correct locale requires more than rendering a selector. The site may infer language from a path, a domain, user preference, a browser header, or a request parameter. Those signals can conflict. A user who manually changes language should not be forced back by a background redirect. The application needs a clear precedence rule and a stable way to keep page identity across languages.
What can go wrong: The frontend chooses the first translation row in a list and shows whichever language was inserted earliest. Test language choice as a continuous interaction. Start on a deeply nested target page, switch languages, follow an internal link, and refresh. If the requested language disappears, note exactly where. A durable route should describe both content identity and the chosen locale, while respecting any deliberate user preference rules.
What to do: Apply explicit language selection rather than relying on row order. Walk through three routes: a new visitor entering from search, a returning visitor following a bookmark, and a reader switching language while on a deeply nested item. Observe the route, content, navigation labels, and next click in each case. If no translation exists, show a deliberate explanation or documented fallback. A selector that merely changes its own label without changing the item content is not localization.
Acceptance evidence: The same selected locale returns the right text regardless of data order. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
14. Design frontend language switching
Directus does not automatically provide multilingual routes for every consuming application.
International search depends on content, URLs, and discoverability working together. A localized title may need a locally natural search phrase rather than a literal translation. A slug is a technical route, and an alternate-language annotation is a relationship between real pages. Neither should claim that a page exists when it does not. The content platform may store descriptions and slugs, but the website usually controls canonical URLs, sitemaps, and alternate links.
What can go wrong: A Spanish station URL redirects to a different station after the reader switches to Arabic. SEO work begins with a real localized page, not a speculative alternate link. Search intent should sound natural to the target audience, with complete answers on the page. Inspect the actual title tag, description, route, canonical, alternate URLs and indexability. Never use international metadata to paper over a page whose essential content is still missing.
What to do: Preserve station identity in route mapping and select the target text separately. Write the principal search intent for each locale in the reader’s own language. Review title, summary, heading hierarchy, route, visible content, and links together. Confirm that the published frontend emits truthful canonical and hreflang signals if those are implemented. Avoid creating target URLs before the translation is substantive. Test a real URL in a browser and inspect its source; a correct CMS record does not guarantee a crawlable page.
Acceptance evidence: The reader remains on the corresponding location after the language change. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
15. Check localized metadata and alternate URLs
The website must generate truthful canonical, alternate-language and sitemap data using Directus records.
Permissions protect the integrity of translations. Content editors may be able to update a title without permission to approve a legal policy, and a machine integration should not automatically publish every target version. Public API access must be the minimum required to deliver published content. Drafts, personal information, internal notes, and unpublished translations should not leak merely because they sit in a related collection.
What can go wrong: A route declares an Arabic alternative even though that translation has never been reviewed. Run role tests with real restricted permissions. Administrators can accidentally hide the fact that an integration has excessive access or that a translator cannot actually save a required field. Test both success and refusal. A good permissions model makes the legitimate task possible while preventing updates to identity, private drafts and unrelated locales.
What to do: Include only real public target pages and locally appropriate titles or descriptions. Define separate responsibilities for source owners, translators, reviewers, publishers, and application integrations. Test each role with an account that has those exact privileges, not an administrator account. Include negative tests: a translator should not modify an operational identifier, a public request should not fetch drafts, and a reviewer should not accidentally publish unrelated locales. Role design is incomplete until those denials are observed.
Acceptance evidence: HTML metadata and visible content agree with the language route. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
16. Protect the public data boundary
Directus access policies can limit which collections and fields are exposed to public clients.
Publication is a state transition, not simply a button press. Depending on the system, a localized field may share its parent record’s publication state, or each language record may be released independently. The difference affects launch dates, approvals, and rollback. Teams should also distinguish publishing content from invalidating a cache or deploying a frontend that can display it.
What can go wrong: A public request receives unpublished translation notes because the entire junction was opened for reading. Carry the exact approval into delivery. Publishing a record may not update a deployed frontend or flush a cache, and preview can show content that visitors are not allowed to see. After release, fetch the public URL in a clean context and confirm the same source version, locale and meaning. Include a rollback path when a serious mistake appears.
What to do: Test exact public read policies for parent, language and translation fields. Build a release checklist using a single target entry. Verify the latest source version, language approval, required fields, links, locale routing, and live API response. Publish only the intended content, then fetch a fresh public page outside the editor. Check the previous language and an unrelated item to catch collateral changes. Record the result, the time and the responsible owner. If any critical condition fails, make the reversal procedure clear.
Acceptance evidence: Anonymous API calls return only intended published content. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
17. Evaluate AI translation controls carefully
Directus documents optional AI translation controls; provider configuration and review remain necessary.
Machine translation and AI can accelerate drafts but cannot define correctness by themselves. Structured fields may include placeholders, technical identifiers, product terms, citations, and policy qualifications that should be protected. Even a fluent draft may reverse a negation or make an optional action sound compulsory. The review standard should depend on the consequence of the words, not on whether a system generated them quickly.
What can go wrong: An automatic draft turns a station restriction into an unconditional accessibility promise. Keep automated translation subordinate to the source record and approved glossary. Validate numbers, negation, conditional clauses, units, links, identifiers and region-specific claims before considering style. If the original is unclear, fix the source or request clarification from its owner; a fluent target cannot repair an unresolved factual ambiguity.
What to do: Protect identifiers, numbers and conditions, and require qualified approval before release. For a controlled test, translate a short text containing a number, a URL, a condition, a disclaimer, and a term from an approved glossary. Compare the target to the source and mark factual omissions and additions. Ask a qualified reviewer to resolve ambiguity. Store accepted terminology and source version, but do not treat the output of one automated pass as publication approval. Automation belongs inside an accountable workflow.
Acceptance evidence: Generated wording remains faithful and does not rewrite shared data. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
18. Test right-to-left content and accessibility
Languages such as Arabic require attention to text direction, layout and mixed-script place identifiers.
Quality assurance must test both language and application behavior. Linguistic checks cover meaning, register, terminology, completeness, numbers, and readability. Technical checks cover fields, links, routing, permissions, rendering, directionality, and publication state. The distinction matters when a sentence is correct in a record but absent on the page, or when the webpage displays a plausible sentence from an unintended locale.
What can go wrong: An Arabic page reorders an English station code and becomes difficult to interpret. Test a happy path and a failure path. The happy path proves that a complete translation can work; the failure path reveals what the product does when a field, relation or permission is missing. Both are needed for a trustworthy release. Give severe defects explicit owners and avoid declaring success until the reader-facing consequence has been checked.
What to do: Use recorded direction metadata where suitable and test real text in the frontend. Create an evidence sheet for each locale: item identifier, source version, expected text, actual API output, visible page, reviewer, and decision. Include difficult examples such as long titles, blank values, nested links, right-to-left layouts, and a late source revision. Assign severity based on likely reader harm. An untranslated decorative tagline should not have the same priority as a mistranslated safety instruction or purchase commitment.
Acceptance evidence: Numbers, proper names and route descriptions remain readable and accurate. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
19. Trace publication, cache and public visibility
Saving a related translation does not guarantee that the frontend immediately displays the updated approved copy.
The first release teaches the team where language actually flows through its product. Instead of celebrating the number of strings translated, monitor missing-content reports, wrong-language routes, broken links, support queries, and search impressions by locale. Read qualitative feedback: a visitor may complete a task yet still misunderstand a warning. Numbers are useful when paired with a concrete investigation of the reader journey.
What can go wrong: An editor sees corrected instructions while the site serves an older cached station description. Use support tickets and analytics to choose the next regression case. A surge of wrong-language exits might reflect routing, while confused questions about a policy might reflect wording. Investigate with a traceable example rather than treating every metric change as proof of translation quality. Publish a correction only after the responsible layer has been identified.
What to do: Inspect permissions, approval state, API response, cache and final page in sequence. Track a small set of quality signals before and after the release. Investigate a surprising change by inspecting route, entry, source revision, and content delivery. Avoid drawing a conclusion about language quality from traffic alone; seasonality, campaigns, and product changes also influence it. Fix confirmed causes, then add that case to regression testing. Quality improves when real failures become durable learning rather than isolated support tickets.
Acceptance evidence: A fresh public request shows the intended approved version. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
20. Govern schema changes and new languages
New translated fields, policies and language codes can affect all existing client queries.
Localization becomes sustainable when there is an owner for changes after launch. New fields, revised source articles, deleted relations, plugin upgrades, and new locales can invalidate old assumptions. A translation system therefore needs documentation that an editor can understand without having built the original application. It also needs a simple way to stop publication when important meaning cannot be verified.
What can go wrong: A new field is added to the junction but mobile applications never request it. Make the system understandable to the next editor. Record what is localized, what stays shared, which locale is the default, how missing values behave, and how a target page is approved. Revisit these decisions when the model or application changes. This is the practical difference between a one-off translation campaign and a maintainable multilingual publication.
What to do: Update schema documentation and regression tests whenever translation infrastructure changes. Maintain a living record of locale rules, content ownership, approved terminology, fallback policy, release procedure, and unresolved exceptions. Review it when the schema or frontend changes. Keep a small regression collection of known difficult items and run it after upgrades. A professional translation operation is not one that never encounters errors; it is one that detects, explains, repairs, and learns from errors before readers are misled.
Acceptance evidence: Old and new locales continue to resolve correct relationships and reader instructions. An acceptable result should name the relevant content item, requested locale, responsible reviewer and exact public or test route. Keep one correct example and one incorrect example, so future editors can recognize the difference. A saved value alone is not proof that the reader receives it.
Twelve real-world diagnostic case files
The following case files are practical exercises for teams publishing with Directus. Each begins with a reader-visible problem, then separates language, data, and delivery causes. They are illustrative situations rather than claims about the configuration of every installation. The diagnostic rule is to locate the first stage where expected meaning and observed meaning diverge.
Case 1: Inspect the parent collection first
Starting symptom: Editors attempt to duplicate an entire station record for every language and create inconsistent coordinates.
An editorial team believes every page is covered because a dashboard shows a translation percentage. The first investigation should ask what the dashboard counts: text fields, published records, whole pages, or links. Build a single reader journey and enumerate every visible message. A percentage is a useful workload indicator but cannot establish that the journey works.
Resolution exercise: Mark stable identity and operational facts before enabling content translations. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: One station keeps one underlying identity across all supported languages.
Case 2: Use the Generate Translations wizard
Starting symptom: A team manually builds a complicated relation that the built-in setup could have generated.
A locale code appears valid but renders the wrong regional spelling. Compare language codes, market identifiers, browser preferences, and the actual API request. The remedy may be a route or selection rule, not a new translation. Keep a screenshot of the requested route and a record of the content field that supplied the text.
Resolution exercise: Inspect the wizard’s chosen fields and generated objects in a safe test collection. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: A languages collection, junction collection and translations alias exist as intended.
Case 3: Understand the languages collection
Starting symptom: A developer treats translated language names as reliable foreign keys instead of stable codes.
A translator changes a technical key because it resembles a word. A visible label improves, but another integration stops finding the record. Restore the shared identifier and move translated wording to the field intended for presentation. Add a field description so the next editor can distinguish a system identifier from reader-facing language.
Resolution exercise: Use configured codes consistently and preserve direction information when relevant. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Spanish and Arabic are resolved by their exact language identifiers.
Case 4: Keep translatable fields in the junction
Starting symptom: An editor adds title_english and title_spanish to the parent, making each new language a schema change.
Two language pages stop linking to each other after a source article is duplicated. Compare the stored relation, translation group, and URL mapping. Fix the identity relationship rather than adding a hard-coded hyperlink only to the page that failed. Then test another item to prove the relation model, not just one exception, is correct.
Resolution exercise: Use the chosen relational translation model for fields that should expand by locale. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Adding a language does not require duplicating the whole parent object.
Case 5: Verify alias and foreign-key relationships
Starting symptom: A copied translation row points to a different station because the parent relation was incorrect.
A long translated heading breaks the mobile layout. Shortening it at random could delete an important condition. First check the content meaning, then the design allowance, line wrapping, and device width. A suitable result communicates the same condition naturally even when it uses more words than the original.
Resolution exercise: Inspect parent key, translation key and language relation as a complete chain. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Every target text belongs to the intended source item.
Case 6: Prevent duplicate locale rows
Starting symptom: A station displays two competing Spanish descriptions because duplicate language rows were allowed.
A related article appears in the source language when a target-language version is unavailable. Decide whether that destination should be hidden, explained, or deliberately offered as a fallback. Do not silently imply it is a translated article. Test the navigation from the user’s actual starting page.
Resolution exercise: Apply validation or database constraints appropriate to the deployment and review existing data. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: At most the intended approved translation resolves for a given station and locale.
Case 7: Choose a missing-translation policy
Starting symptom: A station page shows English accessibility guidance beneath an Arabic heading with no explanation.
A field is explicitly blank but the team expected the default language to appear. Inspect the platform’s treatment of absent values versus empty strings and unpublished variations. Use a clearly documented policy instead of guessing. Build fixtures for each state so later changes cannot silently reverse the intended behavior.
Resolution exercise: State when fallback is allowed and how unavailable translation is signaled. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Missing related language rows never silently change the claimed meaning.
Case 8: Review relational API responses
Starting symptom: A client requests only the parent fields and concludes the Spanish translation is missing.
A link survives translation but points to an outdated procedure. The problem is not a missing word; it is a broken promise about where the reader will go. Check both the link text and the destination’s current content and locale. A technically successful URL response does not prove that the destination is appropriate.
Resolution exercise: Include the needed relation and apply a language filter using the documented API syntax. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: The response contains the intended target row and shared station data.
Case 9: Keep rich text, links and instruction order
Starting symptom: An Arabic paragraph omits a condition about step-free access after formatting changes.
An image contains an English instruction while the page text is in another language. Audit image alternatives, captions, and attached downloads. Either select a language-specific asset or provide a clear accessible explanation, depending on the material. Test what the user actually sees, not merely the metadata stored in the CMS.
Resolution exercise: Review meaning and rendered structure together, including the destination of every linked service. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: The route instructions remain complete and actionable in each language.
Case 10: Localize media descriptions and downloads
Starting symptom: A Spanish station guide links to an English PDF while promising Spanish instructions.
An editor marks a translation finished while the source is still under revision. Compare source version and target approval date. Explain the unfinished dependency and hold publication if the meaning may change. Status labels must describe the real workflow; they should not hide uncertainty by presenting a draft as final.
Resolution exercise: Store translated descriptions in suitable related fields and label nonlocalized downloads honestly. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: A reader can tell which language each asset uses and understands its purpose.
Case 11: Make translation entry usable for editors
Starting symptom: An editor saves Spanish wording under the wrong language due to an ambiguous tab label.
A source policy acquires an exception after translations were approved. Identify every affected locale and every place the condition appears. Reopen those items for targeted review, then verify the visible path a reader follows. Do not assume a fluent older translation still conveys the amended rule.
Resolution exercise: Use understandable language indicators, ordering and review responsibilities. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: Reviewers can inspect and correct the intended locale without altering neighbors.
Case 12: Differentiate shared and local approvals
Starting symptom: A translator changes a parent field while intending only to revise a title.
The API returns the expected target-language text but the browser shows the source. Trace parameters, cache keys, application route state, and component rendering. Identify the first layer where the requested locale disappears. Fix that layer and record the reproducing request rather than rewriting a correct translation.
Resolution exercise: Define the ownership and permissions of parent and translated collections separately. Ask a second reviewer to explain why this particular repair preserves the source’s real meaning and the item’s identity. Then repeat the same procedure in the intended locale with one different specimen. Pass condition: A translator can edit approved language fields but not operational facts.
Worked example: from one entry to a verified multilingual page
Create a test stations collection or use an isolated sample, enable translations for title and instructions, and inspect the generated schema. Add two language rows and separate translated fields without changing the stable station ID. Fetch the record with the appropriate translation relation and language filter. Review public access permissions, render Spanish and Arabic routes, and verify direction, links, shared coordinates and missing-language behavior. The accepted result is one station with correctly related wording, not three unrelated station records.
Write down the intended public sentence before opening the editing interface. Mark each part that expresses a rule, a quantity, a relationship, a date, or a condition. These are the parts most likely to cause harm if their meaning changes. Next, create the target text using the available editor workflow. Review it beside the source with a person who understands the original instruction. Read both versions without their headings and ask whether they would lead a reasonable reader to the same relevant decision.
Now inspect the structured record. Confirm that the translation belongs to the correct underlying item and requested language. Check what happens if one target field is missing, if a relation is unpublished, and if a visitor follows a bookmark instead of starting at the homepage. Request the content through the application or API exactly as the public client will request it. Compare the response with the intended wording, then view the final page on a narrow screen and with a keyboard where possible.
Finally, check the title and description that the published page presents to search engines, the destination of every important link, and any alternate-language relationship. The reader should not be redirected to an unrelated object or an unapproved target page. Only after these checks should the target page be called complete. Save a compact test record containing locale, item ID, route, source revision, reviewer, and outcome; it will become a reusable regression test.
A quality rubric that distinguishes serious failures from cosmetic issues
Treat a changed meaning about eligibility, health, safety, payment, rights, privacy or physical access as critical. A missing instruction that prevents a task is high priority. Incorrect locale routing, missing linked records and wrong-language search descriptions deserve investigation even when the wording itself is fluent. Minor punctuation or layout differences may be lower priority, provided they do not conceal qualifications. Assign severity from the reader’s likely consequence, not the number of characters affected.
Score an item against six independent questions: Is the meaning faithful? Is the language natural and suitable for its audience? Are identities, numbers and relationships intact? Does the requested locale return the right version? Is the published journey accessible and usable? Can the team reproduce the result after another update? A professional review should record a clear answer and evidence for each question rather than an overall percentage with no explanation.
A four-week implementation and learning plan
Week 1 — Map and model
Inventory current languages, source owners, records, localized fields, relationships and public routes. Choose ten representative entries containing simple text, long instructions, one missing value, a relation, and a media asset. Establish the locale matrix and a glossary. End the week with a single approved test specimen, not an estimate of translated volume.
For Directus, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Week 2 — Translate and review
Translate the representative items with context visible to the editor. Check conditions, numbers, abbreviations, references, headings and accessibility wording. Have reviewers explain the target reader’s likely interpretation. Hold back any source passage whose meaning is unresolved. Create a clear list of fields and links that still require technical work.
For Directus, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Week 3 — Test delivery and failure paths
Query source and target locales, inspect API responses, verify frontend routes and alternate-language navigation, then test incomplete records. Include preview versus published behavior, right-to-left text where relevant, mobile width and a public permission check. Turn each discovered fault into one documented regression case with an owner.
For Directus, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Week 4 — Publish a controlled release
Release one complete target-language journey with sign-off from content, language and technical owners. Inspect the public page and critical next action, not merely the CMS save screen. Track reports of wrong-language text and broken routes. Review what should be added to the glossary, documentation and next release checklist.
For Directus, attach the actual locale selection, content identifiers and verification requests to this week’s findings. If a problem cannot be reproduced, collect the reader’s route, time and observed wording before changing production content. A small, verified release gives the next group of translators a trustworthy example to copy.
Practice exercises with model answers
Exercise 1: One field is not localized
Ask whether the field was configured as shared, whether the target value is missing, and whether a fallback is hiding the gap. Answer: preserve the source if it is a genuine shared fact; otherwise make the field eligible for translation and test its public value. In your Directus project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 2: A language switch goes to another item
Check the translation relationship or shared identity, not merely whether two titles look alike. Answer: repair the identity mapping and test language switching in both directions on more than one item. In your Directus project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 3: A translated button opens source-language instructions
Inspect the destination content and route for an approved target version. Answer: link to the correct localized destination or disclose a deliberate fallback, then test the reader’s next action. In your Directus project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 4: A source qualification changes after release
Compare source revisions and identify the affected target languages. Answer: reopen relevant translations, confirm the meaning with the source owner, and verify the visible page before approving the new revision. In your Directus project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Exercise 5: The CMS preview and public page disagree
Compare draft and published state, API selection, permissions, cache and frontend rendering. Answer: locate the first layer where the expected locale or version diverges, rather than translating the sentence again. In your Directus project, write the item identifier, requested locale, expected outcome and evidence needed to prove the answer. The exercise is complete only when another person can repeat your observation.
Frequently asked questions
What does professional translation mean in a structured CMS?
It means preserving approved meaning and relationships through authoring, API delivery, routing and the published reader journey. A page is not complete merely because a field contains target-language words. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
Must every field be translated?
No. Stable identifiers and shared operational facts should normally remain stable. Reader-facing wording and locally relevant explanations may need translation or market-specific approval. The classification belongs in the content model and editorial rules. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
How should we select the first target language?
Consider a documented audience need, an available reviewer, the amount of existing content and the technical effort required. Start with one complete journey and a verified locale code before expanding the whole catalogue. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
Can we use automatic translation?
It can help prepare drafts when configured and allowed. Review every consequential condition, number, named entity, linked destination, legal statement and accessibility instruction. Automation cannot grant publication approval. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
How should an unavailable translation appear?
Choose an explicit policy: a clearly identified fallback, a message that the translation is unavailable, or a withheld page. Do not silently imply complete target-language coverage when a critical field is missing. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
Should a language switch keep the user on the same content?
Normally yes, when an equivalent translated item exists. That requires a stable identity relationship and deliberate route mapping; matching only the visible title is unreliable. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
Are translated slugs enough for international SEO?
No. Search success requires meaningful localized content, an accessible route, appropriate metadata, working links and truthful alternate-language signals generated by the site. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
Why do drafts appear correct while the public page is wrong?
Editors may see preview versions, while public requests use published data, different permissions or caches. Compare the specific request, response, route and rendering to find where the values diverge. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
How do we handle a source change?
Record what changed and why, identify affected target versions, re-review the altered meaning, then retest the published journey. Minor formatting and substantive obligations should receive different review priority. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
Who should approve a translation?
Language specialists review meaning and natural expression. The content or business owner verifies factual rules; technical owners verify delivery, routing and permissions. One accountable release owner joins those decisions. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
What should we test before publishing?
Check locale, identity, shared fields, complete meaning, rich text, assets, links, permissions, API output, route, SEO metadata, mobile layout and a negative case. Keep concise evidence for each result. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
What makes a guide useful after launch?
A named owner, glossary, locale policy, regression examples, change log and a method for escalating defects. Sustainable localization is a process of correcting observed failures, not only creating translated text. For Directus, verify the specific data model and installed release rather than assuming another platform behaves identically.
Official documentation and connected learning
The authoritative source for platform mechanics is the maintained product documentation. Features, permissions and interface labels can change across releases. Use the documentation for your installed version and test the actual workflow in your project. References: Directus content translations; Directus translations configuration; Directus multilingual content walkthrough.
For the larger principles of translation accuracy and ethical publishing, continue with Master Art of Translation | The Complete System for Moving Meaning Between Languages and the Translate Like a Pro | Series Index. The previous platform-specific guide on HCL Commerce multilingual catalog and search addresses a different environment; this article focuses on Directus content architecture, delivery, editorial control and reader verification.