How do you translate a Kirby CMS website using language definitions, multilingual content files and translated URLs without confusing visitors or losing the original content? This Kirby CMS localization guide explains language setup, the Panel, per-language text files, slug translation, template strings, fallback, accessible content and international SEO. It gives practical tests for editors and developers building dependable multilingual sites.
Kirby is a file-based CMS in which page content can be represented by structured text files inside content folders. In a multilingual setup, language versions may occupy matching content identities with separate language-specific files. This makes source and target content inspectable, but the visible result still depends on configured languages, blueprints, templates, routes and the way missing translations are handled.
To translate Kirby like a professional, first choose the intended languages and public URL pattern, preserve a trusted default language, define which fields may differ, translate complete page journeys and check the actual website in every locale. The guide below also covers image metadata, language switching, relationships, right-to-left text, redirects, search, release testing and what to do when a translation is missing or outdated.
Quick summary for a working translation
- Define languages before producing target-language content files.
- Keep the default-language source complete so the fallback behavior is understandable.
- Give each localized page real text, relevant links and appropriate translated slugs.
- Translate interface messages and asset descriptions as well as article bodies.
- Test URLs, missing translations, the language switcher and SEO output independently.
- Use review, version control and rollback discipline before a public release.
Our worked example is a fictional worldwide nature guide with English, German and Japanese versions. Its page about migratory birds includes scientific names, migration maps, local observation advice, image captions and an invitation to submit a sighting. Some values, such as species identifiers, should remain exact. Others, such as explanations and warnings, require natural language and sometimes local context. The same method works for learning resources, portfolios and public-service websites.
Understand Kirby’s model before building translations
Kirby’s official language guide describes enabling multiple languages, creating language definitions, choosing default and secondary languages, and managing translations through the Panel or files. The translating-content documentation explains filenames such as home.en.txt and home.de.txt and the need for a default-language file. It also describes translated slugs, language variables and language-specific URLs.
One common misunderstanding is treating the existence of a content file as proof that the page is genuinely translated. A second file can contain copied source text, missing fields, unresolved links or a misleading claim about a regional service. Distinguish file structure, editorial approval and what the visitor sees: all three matter.
1. Begin with language needs, not filenames
List the audiences and tasks before creating language definitions. The German version of a bird guide may serve readers in several countries, while an observation permit or local hiking warning can apply only in one jurisdiction. Language and country are different editorial dimensions and should not be conflated.
Choose the first few pages using actual reader needs: a homepage, a detailed article, a category page, a downloadable resource and a contact form. A complete route through those pages teaches more about localization quality than a hundred translated titles with no working destinations.
Identify which terms must remain stable. Scientific binomials, registered names, observation IDs and measurement values are not ordinary prose. Give translators a glossary and visual reference so they know whether a word describes a bird’s plumage, migration direction or a named location.
Ask an independent reader to follow the planned journey in their chosen language and explain what they expect next. If the site can provide only a language badge without accessible content, postpone the public language promise until the minimum journey is complete.
2. Enable multi-language support deliberately
Kirby’s documentation explains that multi-language capability can be enabled in the site’s configuration and managed through the Panel. Before switching an existing site, inspect the original content structure and record how its pages are named, ordered and linked.
Enabling multiple languages changes how the installation locates language-specific content files. An unplanned change on a live website can reveal missing files or change URL behavior. Use a staging copy with realistic content and a way to restore the original state if a migration fails.
Read the exact instructions for the Kirby version running in the project; configuration examples from older major versions may differ. Resist using third-party tutorials as the sole source when the official documentation provides the same concept with current syntax.
After enabling the feature, create one simple test page and access it through each configured language. Confirm its title, content, URL and template. This small demonstration separates a successful configuration change from a real public translation.
3. Define a single trustworthy default language
Kirby expects a default language with complete source content to support missing-translation behavior. The official translating-content guide warns that default-language text files are important for fallback. Choose a source that the editorial team can maintain and review consistently.
The default language does not have to be English. It should reflect how the project’s content is authored and maintained. An organization originally writing in German can select German rather than inventing an English source merely because English appears in many examples.
Do not alter the default language casually after hundreds of localized files exist. A change may affect source ownership, expectations about missing values and URL handling. Record the reason, test dependent templates and preserve historical references.
Create a page with a complete default-language file, a partial target file and no file for another language. Observe the resulting behavior. Explain it in plain language to editors before the team publishes a large collection of target versions.
4. Understand language-definition files
Kirby’s language definitions live in the site’s language configuration area and can include a code, readable name, default flag, locale, text direction, translated strings and URL information. The specific supported fields should be checked against the installed version’s documentation.
Use language codes consistently across definitions, content filenames and public routes. A mismatch between a German code used in a file and the code configured for the site can look like a missing translation even when the text has been written correctly.
A readable language name helps editors and visitors, but it does not decide the exact cultural audience by itself. German-language content might require a separate regional review for Switzerland or Austria if the page contains locally regulated claims.
Verify each definition with a test page, dates, a navigation label and a language switcher. Confirm that the front end uses the intended language and that the configured default is unambiguous.
5. Translate pages through content files
Kirby can store versions of the same page in files such as home.en.txt, home.de.txt and home.fr.txt, using language suffixes tied to the configured languages. The folder expresses page identity while the files provide language-specific field values.
A translator should understand the structure of the file, including field separators and keys. They are normally translating the value of a content field, not renaming an internal key or the entire directory indiscriminately. Structural damage can make a page unreadable even when its prose is fluent.
Start with a short representative page and compare the files side by side. Keep the field names consistent while translating titles, summaries and body text. Retain important source links or replace them only with verified target-language equivalents.
After saving the target file, open the target URL rather than trusting the repository diff alone. Check that the page resolves, renders the correct language and preserves headings, paragraphs, links and any embedded content.
6. Use the Panel without hiding the data model
Kirby’s Panel allows editors to manage languages and localized content without manipulating every file manually. That is helpful for teams, but the Panel remains a view of the underlying content system. Editors need to know which language is active and which fields are editable or inherited.
Prepare the Panel experience for people who do not write PHP or work in a terminal. Clear field labels, instructions and permissions help translators distinguish user-facing content from machine identifiers. A confusing editing interface increases translation errors.
Test the most important editor actions: switch language, change a title, edit a body field, inspect a missing translation and save. If the Panel copies text from another language as a starting point, ensure reviewers understand that it is not yet approved target content.
Compare the saved files with the rendered public page. A correct Panel preview can still differ from what a template produces under a particular host, language URL or cache state.
7. Write blueprints for honest localization
Blueprints describe the content that editors can enter. When a site becomes multilingual, the blueprint should help them understand which fields convey meaning and which are shared facts. A default-looking form can be misleading if it treats every value as independently translatable.
Keep a stable species code or source DOI separate from an educational description. Decide which fields genuinely need language variants and how to show inherited values. Where a field is intentionally non-translatable, give editors a reason instead of merely disabling a control.
A field labeled ‘Description’ might be used as article body text, social preview, image caption or search excerpt. Those require different lengths and review standards. Clearly named fields reduce accidental reuse of a long paragraph in a short navigation component.
Run a review using an editor who did not create the blueprint. Ask which items they would translate and which they would preserve unchanged. Revise confusing labels before extending the model to hundreds of pages.
8. Understand fallback and incomplete translations
Fallback can be useful, but it must not misrepresent completeness. If a Japanese page is missing an educational sentence, an English fallback may appear depending on how the content is retrieved or templated. The visitor needs an honest presentation, especially for consequential instructions.
Define separate rules for missing captions, missing whole articles and outdated translation versions. A clearly labeled English original may be an acceptable resource; a silently mixed-language safety warning may not be. A blank result with an explanation can be more trustworthy than an incorrect promise.
Do not replace an approved target text automatically every time the source is edited. A source update should trigger a review of affected language versions. The distinction between a missing value and a stale but previously approved value matters.
Test a complete target page, a partially translated page and an unavailable target page. Inspect what the public site renders, not only what filenames exist. Document the chosen behavior so editors can predict it.
9. Translate URLs and slugs purposefully
Kirby’s translating-URLs guide explains that translated content files can include a slug value so a route is natural in the target language. For example, the English page about birds could use /en/birds while a German version uses /de/voegel.
Localized slugs should be readable and stable. Translating every technical word literally can create awkward paths; using an unreviewed slug can also cause collisions with another page. Agree on the destination and keep a permanent mapping between source and target URLs.
Changing a live slug is a public event. Existing links, bookmarks, QR codes and search results may reference the old path. Plan redirects, update internal links and test what happens to the language switcher after the change.
Open the target URL directly with no prior cookie. Then test the old route, a nested child page, breadcrumb and canonical output. If the page loads only through the Panel’s preview, the public routing policy is not yet complete.
10. Preserve page identity across languages
The same subject may appear under different reader-facing paths while still representing one conceptual page. Kirby’s file-based organization can help preserve this relationship. Avoid creating unrelated page folders merely to make translated names appear different.
A nature guide might have one underlying entry for a migratory bird species with English, German and Japanese text. It should maintain shared factual identifiers, images where appropriate and connections to the same scientific source, even if the public slugs are translated.
If two market pages have genuinely different subject matter, do not pretend they are equivalent translations. A country-specific field guide that excludes species absent in that region may need distinct content relationships and a more careful language switch.
Build a cross-language mapping for one nested page with a translated slug and two links. Confirm that switching languages reaches the correct corresponding item and that returning to the source restores the same conceptual page.
11. Translate site-wide interface strings
Kirby language variables and the t() helper support translating fixed user-interface text. These strings may include navigation controls, form labels, search prompts, empty states and error messages. They are separate from authored page content even when the visitor reads both together.
Do not construct sentences from scattered fragments unless the translation system deliberately supports the grammar required by each language. Word order, plural forms and politeness can vary substantially. A complete sentence with useful context is often safer to translate.
Keep identifiers for message keys stable. Translating the key itself can break template lookup, while leaving an English value unresolved can produce a mixed-language page. Include screenshots and usage notes for ambiguous terms such as ‘Save’, ‘Current’ and ‘Open’.
Test navigation, validation errors, loading states and contact confirmation messages. Translate the actual action the visitor is taking rather than merely replacing English words one by one.
12. Plan multilingual page templates
PHP snippets and templates decide which fields are rendered and how they are wrapped. A translated content file can still show the wrong value if a template ignores the active language or uses a source-language label hard-coded into the markup.
Separate presentation components from editorial text. Reusable templates should accept the correct language context, and fixed labels should come from translation variables. Editors should not have to paste menu text into every article to compensate for an untranslated template.
Test a page with rich content, an image, two related links and a form. Include a target language with longer words and another with a different script so the layout is challenged before production.
Review generated HTML for language attributes, accessible names, links and title tags. A beautifully rendered page in the browser may still fail screen readers or search crawlers if the document metadata is incorrect.
13. Handle different writing directions
Kirby language definitions can describe right-to-left direction, but implementing a right-to-left website involves layout and content decisions. A browser needs correct language and direction context, while individual controls and mixed-script values may need additional attention.
Do not reverse the order of scientific formulas, serial numbers or coordinate values. The visual flow of Arabic or Hebrew prose should not change the identity of a species, the value of a measurement or the meaning of a diagram.
Navigation menus, icon arrows, slide controls and date widgets should be tested with real target-language content. A layout that merely flips every component horizontally can misrepresent information whose direction has a specific meaning.
Ask a fluent reader to inspect long and short paragraphs, tables, links and contact forms on mobile and desktop. Use keyboard navigation and a screen reader where feasible, rather than relying only on visual screenshots.
14. Translate image metadata and diagrams
An image may communicate something that is not visible in a text export. A migration map with English labels is not made Japanese by changing its surrounding caption. Decide whether to provide a translated graphic, an equivalent textual description or a clearly labeled original.
Keep photo credits and licenses intact. An attribution may contain proper names or required wording that should not be casually changed. A language review needs to preserve legal and factual obligations alongside readability.
Alt text should describe the relevant function of an image, not simply repeat the headline. For a map showing three routes, the target description should help the reader understand what distinguishes the routes; a decorative photo may not need a verbose description.
Inspect each language page with images disabled and with a screen reader. Compare captions, credits and any downloadable image descriptions. Check that the selected asset truly matches the translated explanation.
15. Keep scientific names and identifiers exact
Translation often involves deciding what not to translate. Scientific names, dataset IDs, reference numbers and raw observation coordinates belong to the identity of the source material. Changing them for stylistic fluency can disconnect a translated page from its evidence.
For a bird guide, explain the local common name while preserving the accepted scientific name when appropriate. If the taxonomy has changed, document the actual scientific revision rather than silently treating the new name as an ordinary target-language synonym.
Measurements can be displayed using localized separators or explanatory units, but the numerical fact must remain correct. Conversions should have a documented precision policy and must not claim a level of accuracy the source did not support.
Compare the target against a protected list of identifiers and units. If a translator flags a possible scientific error, have the source owner resolve it; translation review should not become an invisible change to the evidence.
16. Localize dates, times and contact details
Locale settings can affect presentation, but a reader still needs an unambiguous factual date and time zone. An event at 7 p.m. in one city does not occur at 7 p.m. in every reader’s local time. Formatting and underlying event identity are separate.
Use full date wording where ambiguity matters, and state the applicable time zone for live events. Localize telephone formats and addresses for readability without changing the actual number or physical location unless a regional service genuinely differs.
Currency conversion should not create invented offers. A Japanese reader can understand a price shown in the operator’s actual currency; a converted approximate figure must be labeled as an estimate and not a checkout price.
Create test cases around a date near midnight, a decimal measurement, an international address and a booking deadline. Compare stored values, rendered displays and confirmation messages.
17. Build trustworthy navigation and breadcrumbs
A translated article is difficult to use if navigation sends visitors back to the default language. Menus, breadcrumbs, category labels, pagination and related-content cards are part of the same localized experience as the page body.
Organize the target site around meaningful categories. A literal translation of an English label may sound unnatural or refer to a different educational level in the reader’s country. Choose terms that preserve the concept and help readers locate related content.
Never build translated deep links merely by replacing a language prefix if slugs and structures can vary. Use resolved page destinations so the reader reaches an existing and relevant item.
Start at the homepage, reach a nested guide, open a related page, return through breadcrumbs and switch languages. Record any point at which the site changes language unexpectedly or offers a link to missing content.
18. Design a real language switcher
The language switcher should show languages available for the current content and point to the corresponding page URL. Kirby’s language and page APIs can provide a basis for constructing these destinations, but the exact template must be tested against the site’s URL policy.
Display language names in recognizable form and make keyboard focus visible. A globe icon alone may not be enough for a reader using assistive technology. The control’s label should explain the action, not just show two-letter codes.
If a target translation is missing, choose a policy that is clear to the visitor. Removing the option, labeling the source-language fallback or offering a related index can all be defensible in different contexts. Falsely claiming equivalence is not.
Test switching from a deeply nested page with a translated slug, an untranslated page and an archived article. Confirm that the switcher neither invents a path nor discards the reader’s subject without explanation.
19. Make forms and user actions multilingual
Visitors often encounter translation gaps after clicking a button. Contact forms, validation errors, subscription prompts, confirmation pages and email notifications need the same attention as headings. Their instructions can affect data quality, privacy and whether a user understands their commitment.
Translate action verbs in context. ‘Submit a sighting’ should not become an imperative that suggests publishing a photo immediately if the workflow actually sends the report for review. Keep consent and reporting responsibilities accurate.
Forms may have technical field names that must remain stable for back-end processing. Translating these keys can break data handling; translating the visible labels should not. Document which values belong to the interface and which belong to a machine contract.
Perform a full dummy submission in every language, including invalid input and a corrected resubmission. Examine the confirmation email and any staff-facing output for language confusion or altered reference IDs.
20. Build a conservative international SEO plan
Multilingual search visibility depends on meaningful content, stable URLs and accurate metadata. Each language page should have a descriptive title and summary, appropriate canonical treatment and correct language identification. Do not advertise unfinished versions in a sitemap or alternate-language set.
Translated slugs can be useful to readers, but a translated slug without an approved body is not a translation. Search engines and visitors may discover a page whose label promises a different language from the actual content.
Where the site outputs hreflang, ensure each target represents a real equivalent and the language-region values are accurate. Avoid pointing every alternate to a homepage or using country codes merely as traffic targets.
Crawl a set of target pages and inspect canonical URL, document title, meta description, alternates, sitemap status and redirects. Check links from search results to ensure the user lands on the promised language.
21. Handle internal search and categories
On-site search may be implemented through Kirby’s own content model or a separate service. The team needs to decide whether a query should search only the selected language or offer explicitly labeled cross-language results. Mixing languages without signaling them is frustrating.
Test words readers actually use. A German visitor may use a compound noun that does not resemble a literal English keyword. A Japanese visitor may search with a familiar script form. Search quality requires vocabulary and indexing choices, not only content files.
Categories and filters need useful target-language labels. Missing labels can produce an English facet in an otherwise Japanese result page, while a category relationship may lead to an unavailable target article.
Check searches with accents, alternate spellings, no-results cases and recently withdrawn content. Verify that index updates keep pace with published translations and that results link to the correct final routes.
22. Make version control a translation safeguard
Kirby’s file-based nature makes content changes visible in version control when the project uses a disciplined repository workflow. That is valuable for review, but a changed filename alone does not show whether a sentence preserves meaning. Both structural and editorial checks are required.
Keep separate review attention for edited prose, changed identifiers, removed fields and new links. A translator should be able to see exactly what source content changed without losing the previously approved target wording.
Use commits with a clear purpose, not vague messages such as ‘fix translation’. Record the affected languages and pages, and keep a rollback route. Ensure sensitive drafts and unpublished personal information are not exposed through public repositories.
Before merging, compare the rendered page in staging and run link checks. Review the diff and confirm no unrelated source language files or configuration definitions changed inadvertently.
23. Test deployment, cache and redirects
A multilingual site can behave correctly in development but fail after deployment because the web server, cache or domain configuration treats language URLs differently. Test the actual production route rather than assuming that the file name guarantees reachability.
Check redirects from older slugs, default-language root behavior, nested routes and cross-domain language URLs. Avoid redirect chains that force visitors back to English or erase a deliberately selected language.
If a corrected warning remains visible in an old version, inspect caching and deployment status. A successful file commit does not prove the content was deployed or that every cached route has been invalidated.
Run direct requests from a clean browser, with and without the trailing slash conventions used by the site. Confirm that canonical destinations are stable and that missing pages produce honest unavailable states rather than unrelated fallback content.
24. Establish approval and maintenance routines
Good multilingual publishing is maintained over time. Assign responsibility for the source facts, translation quality, template behavior and public release. One editor can do several jobs, but the approval should still identify what was checked.
Group source changes by importance. A corrected scientific fact or safety warning needs prompt cross-language review. A minor punctuation edit may not require the same urgency. Never silently overwrite a carefully approved target translation with new source-language text.
Prepare a checklist that includes translation completeness, image and link review, accessibility, metadata, form journeys and the final public URL. Keep evidence of which target versions were reviewed and which are still pending.
After publication, periodically revisit high-traffic language journeys and inspect for broken links or mixed-language components. A site that passed review at launch can deteriorate if new English templates or categories are introduced without translation coverage.
Complete worked example: a migration guide for an international audience
Imagine the source article ‘Understanding migratory bird routes’. It contains a scientific introduction, three routes on a map, dates for seasonal observation, a table of average distances, references to public datasets, photographs and a visitor submission form. The team first identifies which parts are stable evidence and which parts need language or region-specific interpretation. The route boundaries and reference dataset IDs remain factual anchors; the prose can be translated for clarity.
The English page has its default-language content file. German and Japanese target files are added under the same content identity, using the language codes configured for the site. Titles, summaries, explanations and image descriptions are translated. The scientific names are checked against a trusted list and the map is evaluated for embedded English labels rather than assumed to be language-neutral.
The German reader-facing URL uses a translated slug where appropriate. The Japanese URL follows the site’s published conventions and is checked for correct encoding, readability and redirects. The team updates language-switch destinations using resolved page URLs. Each target page gets its own accurate search description and is omitted from alternate-language signals until it is ready.
During review, the German text explains the map correctly but a related link points to a withdrawn source article. The editor replaces the link with a verified alternative, recording the change. The Japanese text is fluent but uses an ambiguous word for an observation period; the subject reviewer clarifies that the original refers to migration season rather than the date an individual bird was observed.
The submission form accepts an observation with a date, location and optional photo. The team tests errors and confirmations in both languages while preserving coordinates and reference IDs. When the source scientific reference later changes, the update is classified as a factual revision and all relevant versions are reviewed before a new publication is announced.
Troubleshooting: what to check when multilingual Kirby looks wrong
The language option appears but its page does not
Confirm the language definition, code-matched content file, routing and publication state. Do not invent a file simply to suppress the error.
A German page displays English paragraphs
Inspect missing fields, fallback policy and template retrieval. Decide whether the fallback is allowed or the page must be withheld.
A translated slug gives a 404
Check the slug value, parent routes, source folder identity and redirects. Test the path directly after deployment.
The default-language page disappears after setup
Review source file naming and the default-language definition. The official guide stresses preserving valid default-language files.
A translated headline changes but the browser title does not
Inspect which field the template uses for the title tag and whether it is still hard-coded or using the source value.
A menu sends visitors back to English
Check navigation item resolution and actual target-language URLs, not just the language prefix.
Image captions are correct but the diagram is English
Create a localized graphic or an accessible textual alternative; a translated caption cannot rewrite labels inside the image.
The language switcher opens an unrelated page
Use the mapped counterpart of the current page and handle missing translations honestly.
The search interface ignores Japanese queries
Check index content, tokenization and language filtering in the actual search implementation; the CMS content file is only one layer.
A field changes unexpectedly in every language
Review whether the value was intentionally shared or whether the editor altered a source/configuration field instead of a target version.
Right-to-left content looks broken
Inspect language direction, mixed-script text, controls and layout in a browser with actual target-language content.
An old translated URL stays in search
Verify redirects, canonical output, sitemap status and indexing updates after the route change.
Four-week implementation and learning plan
Week one: identify audiences, languages, default content, important content types and public routes. Build a source and target inventory including links, assets, forms and expected alternate-language destinations. Choose a modest pilot with a complete reader task. Review content restrictions and stable identifiers before creating files.
Week two: configure languages on staging, establish conventions for default and translated content files, prepare blueprints and template strings, and create test pages for missing values, translated slugs and language switching. Confirm behavior against the official documentation for the installed version.
Week three: translate the pilot page journey, images, captions, accessibility descriptions, related links and form messages. Ask a fluent reviewer to explain the content in ordinary language and complete its tasks. Separate factual mistakes from route, layout and search problems so each can be corrected at the right layer.
Week four: verify public URLs, metadata, canonicals, alternates, sitemaps, redirects and deployment. Publish only complete approved versions, preserve a record of source revisions and establish a review routine for future content updates. Extend cautiously to the next subject collection.
Frequently asked questions
Can Kirby support more than two languages?
Yes. Kirby’s multi-language guide describes configuring multiple languages, including their codes, names, locale behavior and URL rules. Each new language still requires meaningful content and review.
Do translators need to edit files manually?
Not necessarily. The Panel can manage language-specific content, while file workflows remain useful for developers and version-controlled projects.
What filenames does Kirby use for translations?
The official content guide illustrates language-specific files such as home.en.txt and home.de.txt. The suffix must agree with the configured language code.
Why is the default language so important?
Default-language content supports fallback and gives editors a trusted source. Incomplete or misnamed default files can produce confusing behavior.
Can I translate slugs?
Yes. Kirby supports a translated slug field on target-language content; treat URL changes as public changes requiring redirects and internal link checks.
Does setting a locale translate the article body?
No. Locale and language definitions help the application represent and display languages. The actual educational prose still needs a translation.
Can one image be shared across languages?
Often yes, provided the image is appropriate and its captions, credits, accessible description and embedded words are handled correctly.
Is an English fallback always a problem?
No. It can be useful when honestly labeled and permitted for the context. A safety instruction or contractual condition may require stricter handling.
How should I handle scientific names?
Preserve accepted identifiers, explain relevant local common names and ask a subject reviewer to approve any genuine change in taxonomy or facts.
Do language switchers need a separate homepage per language?
They need trustworthy destinations. On a detail page the best destination is usually the corresponding translated page, not an unrelated homepage.
What makes a translation ready for publication?
Accurate meaning, correct links and assets, accessible page behavior, appropriate metadata, direct public URL testing and a recorded approval.
How do I prevent the site from becoming mixed-language later?
Maintain an inventory of new components and source updates, review fallback behavior, and periodically test complete target-language journeys.
Official documentation and useful connected reading
Read the current Kirby documentation for the exact configuration and API used by your installed release. The practical decisions in this guide are intended to help editors and developers ask the right questions and verify results, not to replace the authoritative details of a production system.
Kirby CMS — Translating Your Content