Grav CMS multilingual websites work by connecting language configuration, page-specific Markdown files and theme behavior. If you need to translate a Grav site, the practical first step is to understand which file serves a requested language, what happens when a translation is missing and whether visitors can reach equivalent content through the language switcher.
This guide covers Grav multilingual setup, languages.supported, default_lang, language-suffixed files such as default.en.md and default.fr.md, content_fallback, LangSwitcher, SEO and release testing. Rather than treating every locale URL as a finished translation, it follows the route from stored content to the page a reader can actually understand.
Grav’s mechanisms do not write the translated paragraphs for you. A professional localization workflow preserves meaning and user actions while making page labels, media, forms and navigation work as a coherent edition. Every promise in the interface should correspond to an available, reviewed resource.
Quick setup: two languages and an explicit fallback
Grav’s documented system configuration provides the language policy. This is an illustrative fragment; check your installed Grav release before using it verbatim.
languages:
supported:
- en
- fr
default_lang: en
include_default_lang: true
include_default_lang_file_extension: true
content_fallback:
en: ['en']
fr: ['fr', 'en']A content folder may contain default.en.md and default.fr.md. If the French file is absent, fallback behavior must be tested and the English prose should not be mistaken for a French translation.
1. What a Grav page actually is
Grav is a file-based content management system. A folder and its Markdown source are central to the page’s structure, with front matter describing title and other metadata. Once languages are introduced, several language-specific content files can live beside one another without duplicating the entire website.
Before translation, inspect the folders behind an ordinary article, the home page and a page containing media. Record template filenames, shared assets, page URLs and field conventions. This simple inventory will show where a change belongs and avoid accidental edits to unrelated pages.
2. Set supported languages with a real publishing plan
The official documentation describes languages.supported under system configuration. It tells Grav which language contexts the site recognizes, but does not by itself create translated content. Adding French to a list can produce a site that looks partly French while the articles remain in English.
Start with two languages for which the team has reliable editors. For each, define which pages are available, which are awaiting translation and how unavailable editions should be described to visitors. Add further languages only after the basic reader journey is tested.
3. Choose a default language deliberately
The default_lang setting determines the baseline language of the site when no explicit target locale is requested. This is especially important for bookmarks, incoming links and users who have never selected a preference.
Open the home page and a deep article link in a fresh browser session. Compare the displayed prose and document language with your policy. If a selected language persists through a cookie or session, ensure it does not conceal incorrect default behavior.
4. Decide if the default language needs a URL segment
Grav documents include_default_lang as an option controlling whether default-language routes carry a prefix such as /en/. That affects public addressing, not just visual presentation, and may have consequences for existing links.
Before changing it on a live site, list established article URLs and redirect requirements. A project with many indexed /about addresses should not casually replace them with /en/about. Preserve readers’ ability to reach the original information.
5. Understand default.en.md and default.fr.md
With multilingual content enabled, Grav can use language-suffixed Markdown files such as default.en.md and default.fr.md within a single page directory. A corresponding file stores the prose for that edition rather than a mechanical pointer to an automatic translator.
Translate one small test page and visit each language route. Verify headings, body, links and metadata. Be careful with copied front matter: a copied title or field can remain in the old language even when the article paragraph has been updated.
6. Know why default.md still matters
Older or single-language Grav sites often have an unsuffixed default.md. The interaction among existing files, language settings and the installed version affects the displayed fallback content. A French route can therefore sometimes surface the default-language page.
Inventory unsuffixed files during migration. If the output displays English under a French URL, determine whether that is an intended fallback or a content-selection problem. Do not mark the edition complete simply because the route returns a page.
7. Review the file extension convention
Grav’s language options include include_default_lang_file_extension, which determines whether the default-language file uses a suffix. A consistent convention can simplify editorial work, while accidental mixing can make updates harder to track.
Decide the convention according to your actual Grav release and existing page structure. When renaming a file, run a staging build and inspect metadata, routes, child pages and media. A filename migration should not unintentionally alter the reader-facing page.
8. Choose a content_fallback policy
The Grav 1.7 documentation describes content_fallback mappings, such as looking first for French content and then English. It notes that multilingual fallback behavior changed from older releases, so configuration examples must be checked against installed software.
Write a policy for untranslated articles. An English fallback may help some readers, but it should be labelled as English. A legal or safety-critical page may require a different approach until qualified reviewers approve the target-language edition.
9. Test missing translations intentionally
A multilingual release that tests only finished pages misses one of the most common failures. A language selector may point to a page that lacks the requested Markdown file, generating an alternate-language URL that shows original-language prose.
Prepare one complete translation, one incomplete translation and one page with no target-language file. Note the actual route, displayed language, notice and availability of a way back. Correct the policy before telling visitors that the entire site supports the language.
10. Explain fallback status to visitors
A fallback is useful when a reader needs information immediately, but it is not a translated edition. Hiding that distinction can affect comprehension and trust. Visitors might wrongly assume that an untranslated warning is appropriate for their reading language.
Use a concise, visible statement when the content is available only in another language. Keep the route honest and offer a supported alternative. A language indicator must describe the prose that is actually read, not merely the menu that surrounds it.
11. Use LangSwitcher within the theme
The Grav documentation describes a LangSwitcher plugin that can be installed from the Admin interface or through GPM. It supplies a path toward a language selection control, but the actual appearance and page mapping depend on the selected theme and its integration.
Test the switcher from a homepage, a bilingual article and an article without a translation. When a corresponding page exists, the switch should reach it. If the target is absent, an explicitly labelled language home link is better than a silent, confusing redirect.
12. Use recognizable language names
A language menu may display names, abbreviations or flags. Prefer labels that actual speakers can recognize; flags are imperfect representations of languages spoken in many places. Where regional varieties matter, describe them precisely.
Check mobile widths, keyboard operation and accessible names. A reader should know which language is currently selected and should be able to change it without scrolling through hidden controls or using a pointing device.
13. Separate page text from theme strings
The contents of default.fr.md and the labels produced by a Grav theme are different localization layers. Translating a page does not necessarily translate a Search button, cookie notice, pagination label or shared footer.
Trace an untranslated string to its owner before editing. If it is in the body, use the page translation workflow. If it is in Twig or theme language resources, use the theme’s localization conventions. Avoid blanket search-and-replace operations across structural files.
14. Review Twig rendering context
Grav themes commonly use Twig templates. They may contain user-facing text and control how fields, child pages and navigation links appear. A template can produce the wrong language even when the Markdown source is correct.
Inspect a representative card, breadcrumb, footer and list view. Confirm which values are translated and which remain shared identifiers. Test template changes in staging and inspect the generated page rather than assuming an added language entry reaches every element.
15. Name translation keys by purpose
A well-designed message key describes a function such as navigation.search or form.submit. A key describing a button’s color does not tell a translator what it means or survive a redesign well.
Add context for short ambiguous words. Open could be an instruction to expand an accordion or a status label; the target words may differ. Review each translated value in the component where the reader encounters it.
16. Protect placeholder meaning
Theme messages may contain a quantity, a user name or other variable. The target-language words can move around such values, but the placeholder must still render the correct data. A lost count can turn a reliable interface into a misleading one.
Test zero and multiple counts, very long names and punctuation. Keep technical placeholders recognizable to editors, and avoid translating identifiers that the template needs to find at runtime.
17. Understand front matter risks
Page front matter can contain natural-language titles and machine-facing settings in the same block. A translator should not assume that every YAML value is text to localize. Template identifiers, publication flags and routing controls can affect the page’s behavior.
Provide a short field guide with examples of translatable and protected values. When saving a translation, check that only intended wording has changed. Reload both language editions to catch accidentally shared field edits.
18. Check Admin field ownership
Grav’s Admin editor and blueprints may expose fields shared across editions or fields associated with the current language. A localized editor interface alone does not guarantee that every edit is language-specific.
On a harmless staging page, save a French field and reopen English. Record which values remain shared. This prevents a contributor from replacing an original page’s structural data while trying to write a translated description.
19. Preserve page identity between languages
The same underlying guide may have quite different titles in English and French. Translating a title is not the same as creating an unrelated article. The page folder and configured routes should support a stable relationship.
Open source and target editions side by side. Check whether they address the same reader question, contain current conditions and connect through the switcher. Do not choose an apparent counterpart by keyword similarity alone.
20. Keep menus in the reader’s edition
Menu labels and link destinations must be tested together. A French navigation bar can look polished but lead to English-only pages or a different level of the site because it inherits default-language URLs.
Follow primary links and breadcrumbs in a new browser session. If an equivalent page is missing, indicate that clearly. Measure success by whether the visitor reaches an understandable destination, not just by how many labels were translated.
21. Localize forms, hints and consent text
Forms contain required messages, labels, explanations, errors and success confirmation. Those strings may be owned by a plugin. Translation must preserve the actual data being collected and any consequential consent statement.
Submit valid and invalid test entries in each language. Confirm that error messages help users fix mistakes, and that backend field names or permission semantics have not changed merely because the display wording has.
22. Review search within the active language
Site search can index articles in one or many languages, depending on the theme and search integration. Translating the search prompt does not change the scope or relevance of its index automatically.
Test a word found only in French content, an accented term and a search that should return nothing. Check the result language, destination link and no-results instructions. Readers should not be sent unexpectedly to a different-language document.
23. Protect technical text and numeric values
A translation may include code, URLs, filenames, amounts, dates, measurements and version numbers. Their values should be preserved or transparently converted rather than casually rewritten for fluency.
Mark exact technical tokens before review. Run an example command from a translated page and check one ambiguous date and decimal quantity. High-stakes meaning can be lost through a single altered symbol.
24. Review media and attached documents
Screenshots, diagrams, image labels, videos and PDF downloads can contain language-specific instructions beyond the Markdown body. An accurate translated paragraph may still depend on an untranslated figure.
Inventory media with embedded words. Translate important captions and alternative text, localize critical assets where feasible and disclose when a supporting resource remains in another language. Check its link from locale-prefixed pages.
25. Test the HTML language of each page
The document language should describe the prose readers actually receive. An English fallback on a French route needs honest identification rather than blindly inheriting the locale prefix. Assistive technologies use language metadata for pronunciation.
Inspect rendered HTML for a true French page, an English fallback and a page quoting another language. Check that visible notices and screen-reader output make the source language clear.
26. Test right-to-left reading
Arabic and Hebrew expose direction problems, particularly with punctuation, URLs, phone numbers and code. Translating menu labels alone does not produce a usable right-to-left edition.
Ask a proficient reader to inspect a sample containing mixed scripts and numeric information. Test navigation order, forms, long labels and technical strings at mobile widths.
27. Distinguish canonical from alternate URLs
A canonical URL identifies the primary address of a resource. An alternate-language link claims another page conveys equivalent content in a different language. Fallback material is not automatically an approved translation.
Open the actual alternatives in both directions, examine page metadata and remove any invented counterpart links. Do not construct alternate paths from locale codes without checking content availability.
28. Translate summaries truthfully
Search titles, descriptions and social previews should accurately describe the actual page. A French snippet is not helpful if it advertises a translated guide and sends the reader to untranslated English prose.
Review each summary with the introduction and target-language article. Keep natural search phrases without keyword stuffing, and label any deliberate source-language fallback.
29. Protect stable routes
Localized slugs can communicate meaning, but URLs are public identifiers. Changing one may break bookmarks, search listings and internal language-pairing records.
Maintain a source-to-target route map and check redirects before release. A translated headline can change without requiring a new permanent URL on every edit.
30. Localize categories with clear ownership
Archives and taxonomies contain language-sensitive labels outside the Markdown body. A target-language archive can accidentally mix translated and untranslated posts or use English category labels.
Choose a consistent identity policy for categories and verify visible result languages, counts and links. A translated category label should not falsely imply that every listed item is available in the selected language.
31. Preserve dates and numeric values
A date with two numbers may have different interpretations across countries. Prices, percentages and technical measurements may need localized formatting, but their factual values must remain intact.
Test an ambiguous date and a decimal quantity. When converting money or units, label the rate or method and avoid silently replacing the original fact with a different one.
32. Translate form flows completely
A contact form includes field labels, required warnings, submission confirmation and sometimes legally significant consent wording. Plugin-controlled messages may not be translated by changing the page body.
Submit valid and invalid test forms in each locale. Check that translated feedback corresponds to the real backend behavior and that identifiers used by integrations remain exact.
33. Account for media with embedded language
An accurate French paragraph can still depend on an English infographic, screenshot or PDF. Critical instructions hidden in media are part of the content readers need.
Inventory visual assets, translate captions and alternative text, provide target-language replacements where feasible and label resources that remain in the original language.
34. Keep executable examples exact
Tutorials often contain command flags, file paths, software identifiers and configuration snippets. They must not be translated like ordinary vocabulary.
Protect syntax from typographic substitution and test an example from the target-language page. Translate surrounding explanation while preserving the bytes that software expects.
35. Track source changes
A translation can become stale when its source changes a deadline, warning or required procedure. Fluency does not prove factual currency.
Record source revision and target approval. Give urgent priority to changes in must, not, only, before, after and numeric thresholds, then compare the actual reader action.
36. Test long interface strings
Some languages require more space for a menu label or form instruction. Fixed-width controls can clip information while the build reports no error.
Test small screens and enlarged text. Maintain accessible touch targets, allow reasonable wrapping and avoid unexplained abbreviations used only to preserve the original layout.
37. Check keyboard journeys
A translated language switcher must work without a mouse, have an understandable accessible name and lead to the intended page. Hidden focus and wrong-language announcements can block use.
Navigate from home to an article, switch language and return to an archive using only the keyboard. Repeat on a missing-translation page and verify that the alternative destination is explained.
38. Combine linguistic and technical review
A developer can miss a mistranslated negative; a language editor can miss a broken link or corrupted code snippet. These are different quality checks.
Ask a fluent reader to explain the page’s instructions and a technical reviewer to validate the routes, values and executable fragments. Both assessments should use the current published version.
39. Use staging before public rollout
Site-wide language settings affect more than one article. Testing in a staging copy reduces the risk of publishing widespread routing or fallback errors.
Verify a fully translated page, untranslated page, deep nested route, search result, form and media download. Compare the output with a clean baseline before release.
40. Monitor the public deployment
A language route may work in staging but fail behind hosting redirects or stale generated files. Actual page delivery is the decisive test.
Open public URLs in a clean session, review 404 reports and inspect metadata and links. Correct issues in the new locale without destabilizing the original-language site.
A worked example: fallback versus translation
A nonprofit has translated its Grav home page into French but not an article on benefit eligibility. It enables French navigation and finds that the article can nevertheless be reached from a French URL. The body is English, supplied by a fallback. The address and French menu make it look like a completed French guide.
The editor first marks the actual language and explains that no French edition is available. A qualified reviewer then prepares a French content file, preserving eligibility thresholds, dates, conditions and exceptions. After the file is saved, the team verifies which Markdown version Grav selects, where the language switcher leads and whether the output metadata advertises only real equivalents.
A fluent reader should be able to describe who qualifies and what action is required without reading English. A functional reviewer checks links, form messages and the page’s visible language. The site has completed translation only when the reader can understand the correct information through a dependable route.
41. Separate regional variants when they matter
A language is not always a single uniform edition. Readers in different regions may need different terminology, date conventions or regulatory guidance. Create separate regional content only where those differences meaningfully affect the information or user action.
Record which pages truly need variants and avoid duplicating an entire site without a maintenance plan. The language selector should distinguish regional editions clearly rather than pretending that one flag represents every speaker.
42. Check domain-based language routing
Grav documentation describes environment-based language handling for advanced deployments using different domains or host environments. This requires more care than ordinary language directories because canonical hosts and redirects are involved.
Verify SSL, server routing, domain configuration and the selected default language for each host. Test a deep article link across languages, not only the home page, and ensure external links do not send readers into an unintended edition.
43. Preserve ownership of custom blueprint fields
A site’s blueprints may add custom fields for product data, downloadable files or editorial classifications. Some values belong to a language edition; others describe the underlying resource and should remain identical across editions.
Before localization, label each field as translatable, shared or controlled. Test a harmless change to one target language and verify that source data has not been overwritten. This prevents language editors from altering product identity or routing.
44. Give editors a repeatable page procedure
A new contributor should know how to find the source file, add its language-specific counterpart, translate the right fields, preview the rendered page and connect it to existing language navigation.
Provide a small completed example, including a page with media and a known missing translation. Ask a new editor to perform the task without extra instructions. Any confusion reveals a procedure that needs clearer documentation.
45. Explain translation status in the editorial inventory
A page can be untranslated, being translated, under review, approved, stale or deliberately excluded from a locale. A single yes-or-no field rarely captures enough information for international publishing.
Keep a lightweight status record linking the source page, target locale, source revision and reviewer. This helps editors distinguish missing language files from intentionally hidden pages and avoids false claims of full coverage.
46. Verify the action behind translated buttons
Words such as Save, Delete, Submit and Cancel carry functional consequences. They should describe what the button truly does, especially where forms or account management plugins are involved.
Test the action with a harmless account or staging form. A localized label must not promise a reversible operation if the underlying action is permanent, or suggest that submission is optional when it is required.
47. Check empty and error states
Most readers see successful pages, so missing search results, invalid forms and 404 screens are often overlooked. These states can reveal source-language messages even when every ordinary page looks translated.
Deliberately trigger a missing article, an invalid field and an empty search. Verify that the message states what happened, offers a usable recovery path and preserves the language choice where feasible.
48. Keep external citations verifiable
Translated pages sometimes cite reports, official regulations or technical documentation. The cited source may exist only in another language, and a translated source title may not be the document’s official name.
Preserve enough identifying detail—publisher, title, document number or link—for verification. Mark unofficial translations where needed and do not silently modify citations simply to make the page appear entirely localized.
49. Update images when software controls change
A localized tutorial can fail because its screenshot shows an older product interface. The problem is not a language mismatch alone; the depicted control may have moved or changed behavior.
Record the software release represented by important screenshots. Pair image review with text updates and explain version differences honestly. Do not fabricate interface labels that a reader cannot actually find.
50. Test file downloads across deep routes
Relative links can work from the home page but fail from a deeply nested locale route. This is common when page assets or PDF links are assembled without considering the path from which they are requested.
Open every critical download from a deep translated article on the production-equivalent host. Check the response, filename and document language. A translated download label should not conceal an untranslated file.
51. Review privacy and consent statements
Privacy notices often contain obligations and rights rather than mere promotional language. A mistranslated time period or exception may change what a visitor believes about the use of their data.
Use qualified review when the legal significance is substantial. Check dates, definitions and links to complete policies, then confirm that the form interaction matches the statement in every supported language.
52. Use a clean, reproducible build
Old generated files or cached site output can remain visible after a translation is removed. This makes it appear that a missing edition still exists and can corrupt the language switcher’s assumptions.
Build from a known source tree and inspect the resulting directory structure. Compare the published route inventory with approved translation files. Remove stale artifacts through the deployment process rather than hiding their links.
53. Investigate misdirected language switches
When a language switch unexpectedly opens the homepage, the cause may be an absent counterpart, a theme integration rule or an incorrect route mapping. These cases need different fixes.
Check whether a true translated page exists. If so, repair the equivalent-page destination; if not, label the language home or original-page link. Never misrepresent a homepage as the translation of an article.
54. Read a page as a user, not as a builder
Technical configuration proves that a route can be produced, but it cannot prove that the target-language instructions are understandable. The reader’s task is the final quality test.
Ask a fluent person to follow a representative article without the source text. Listen for confusion about timing, exceptions, quantities or next steps. Revise the text and retest the same task.
55. Choose a sensible publication sequence
Launching every language and every article at once can create a large hidden backlog of incorrect links and incomplete translation claims. Smaller staged releases provide clearer evidence about what works.
Publish a reviewed pilot, inspect public output and expand by topic or locale. Keep unapproved content out of the set of declared equivalents. A narrow but reliable launch gives readers more value than an impressive yet misleading language menu.
56. Record the acceptance result
An editorial approval should explain what was checked and which source revision the translation follows. Without a record, future editors cannot determine whether a page was ever linguistically reviewed or merely imported.
Store a concise result: page identity, target language, source version, reviewer, verified public URL and open issues. This keeps correction and maintenance practical without turning writing into bureaucracy.
57. Respond to reader reports
A visitor may discover a mistranslated exception, a broken language link or an outdated screenshot after release. Their report is valuable evidence for improving the page, not a reason to ignore the rest of the system.
Capture the actual URL, selected locale and problem description. Prioritize meaning-changing defects, make a targeted correction, then verify the original and target pages still match. Report resolution through an ordinary editorial update where appropriate.
58. Define a trustworthy multilingual site
The real outcome is a set of comprehensible, maintainable language editions. A site is not translated simply because configuration lists languages or a menu shows flags.
Measure approved target-language pages, stale translations, broken locale links, accessible navigation and reader comprehension. Keep status honest and make the next improvement visible. The reader should always know which language they are receiving and how to continue.
Practical release walkthrough
Imagine a small documentation site preparing English and French editions. First list its real source pages and identify one home page, one nested article, a form and a PDF. Configure the supported languages and create a French Markdown counterpart for the article. Verify that its title, body, metadata and source revision all describe the intended French text rather than a copied English file.
Next, test the language switcher from the English page and confirm it opens the correct French counterpart. Visit a page without a French translation and inspect the configured fallback. If it shows English, label that fact and avoid claiming a real alternate French edition in metadata. Then test the form’s error messages and the PDF link from the French route.
Finally, run a fresh build, inspect actual generated HTML and ask a French reader to use the page for a normal task. The reader should understand the instruction and reach all necessary resources. If any part of the journey changes the subject, version or required action, repair it before publishing. This sequence connects code-level routing checks with human comprehension.
Frequently asked questions
Does Grav translate Markdown automatically?
No. Grav chooses and renders content files for configured languages. The prose inside those files must be authored or translated and reviewed.
What is content_fallback?
A documented setting controlling which language is used when a requested page file is absent. Check your installed release and describe any fallback honestly.
Why does a French route show English?
The French file may be missing, the default-file convention may differ or the configured fallback chain may be selecting English. Inspect source files and final output.
What is LangSwitcher?
A Grav plugin for providing language selection through a theme. Test counterpart destinations and unavailable translations in your own setup.
What is the minimum release test?
Check genuine translated prose, language and canonical metadata, honest fallback, navigation, forms, media, accessible controls and fidelity of important factual conditions.
Official sources and related translation reading
For configuration, see Grav’s official multilingual content documentation and the Grav documentation hub; use the materials matching the installed release. For general principles of meaning and equivalence, read Master Art of Translation. For other implementation-specific guides, visit the Translate Like a Pro series index. This chapter’s practical scope is Grav content files, language routing, fallbacks and public quality testing.