Administrator comparing two language layouts on a widescreen monitor beside a printed phrase checklist
XenForo
17 min read

A XenForo language is a pack of interface phrases plus a few rules: locale, text direction, decimal character, week start, date format. Install a second language and guests can switch the buttons. The threads they already wrote stay in the language the author typed. That split is the whole product. Treat a language pack as a translation of the community’s posts and you will spend a year in the phrase editor for a result the software does not offer.

This is not the custom user fields article. A preferred_locale choice field is a fact you can target with a notice or a promotion. It does not switch XenForo’s language. Official languages live under Appearance → Languages. Official phrases live under Appearance → Languages & phrases → Phrases. The PWA can use one of those installed languages. A user field cannot replace any of that.

Official manual: User interface text: Language and User interface text: Phrases (docs.xenforo.com/manual/appearance/languages, …/phrases). Pre-built packs: XenForo Resource Manager category translations-2-x.48. Where those pages are silent — automatic thread translation, hreflang in the ACP, per-node languages — this article stays silent.

What a language is (and is not)

Official: all user-interface text can be translated “without having to edit any HTML or templates at all,” through phrases, which belong to languages. One installation may have multiple languages. Visiting users can select them.

Official analogy: languages work like styles. A language is a named collection. You manage the collection, not a thousand loose strings in PAGE_CONTAINER.

Object Job Does not do
Language Groups phrases + locale/RTL/date rules Translate member posts, titles, or custom fields
Phrase One UI string, optional {variables} Change permission logic
Default language What visitors get before they pick Override a member who already chose
User field preferred_locale A searchable preference for notices and staff Switch the interface
PWA language One installed language for the installed app chrome Follow each member’s language choice

Members still write English in an English thread while their UI is Polish. Moderators still read the post in the language it was written. If you need two communities (an EN tree and a PL tree), that is nodes and culture, not a language pack. A language pack is the chrome: “Post thread,” “Watch,” “Mark read,” date stamps, the registration form.

Install a language before you translate one

Official: you can translate the entire system yourself. You will not, the first time. “Installing a new language is a simple task and can be managed by most administrators.”

Path: Appearance → Languages. Import the XML from a pack built for your XenForo 2.x line. The Resource Manager category official docs name is translations-2-x.48. Match the board version. A 2.2 pack on 2.3 will leave 2.3 phrases in English (or in the parent). That is inheritance, not a broken import.

After import:

  1. Open the language in the language manager.
  2. Check language settings (next section) — locale, direction, decimal, week start, date format. Pack authors usually set these. Confirm them anyway. Official: “These settings have wide-ranging effects, so ensure that you set them carefully.”
  3. Decide whether visitors may select it. Official: every installed language is selectable by default. A toggle on Appearance → Languages prevents selection of a specific language. Use that for a half-finished child, or for a staff-only proofing language.
  4. Do not make it the default until you have clicked through registration, a thread view, a conversation, and the editor in a private window.

If you finish your own translation, official: use the Export tools in the language manager and, if you want, add it to that same Resource Manager collection. Export is also how you back up a child language before an upgrade.

Default language

Official path: the Appearance section of the main XenForo options, Default language. That is the language for visitors who have not stored a preference.

Pick the language of the people who have not registered yet. A Polish-first board with English as default trains Google and guests on the wrong chrome and then surprises them after they create an account. A bilingual board with no majority should still pick one default. Official software will not geo-detect. Do not invent an ACP “detect from browser” toggle; the pages cited here do not document one.

Members pick a language in their preferences. After that, the default no longer owns their session. Staff support gets easier if you can switch your account without changing the site default. That is what the language chooser is for. The prevent-selection toggle is how you hide a language from that chooser without deleting the pack.

Language settings: locale, RTL, numbers, dates

Click a language in the language manager. Official editor fields:

  • Locale
  • Text direction — left-to-right or right-to-left
  • Decimal point character
  • Week start day
  • Date format

These are not cosmetic. Date format changes every timestamp on the site. Decimal character changes how numbers render. Week start changes calendars. Locale affects language-aware PHP/ICU behaviour XenForo relies on. Official warning stands: set them carefully.

RTL is a first-class official setting, not an add-on. Arabic, Hebrew, Persian, Urdu packs should ship right-to-left. After you enable RTL:

  • Walk a thread view, the editor, the visitor menu, and a modal. Stock 2.3 styles understand direction.
  • A custom style that hard-codes left: in extra.less will break. That is a style bug, not a language bug. Fix it in a child style.
  • User-generated BB code with centered images still works. User-generated tables with explicit left alignment may look odd. That is content, not a phrase.

Do not run an LTR language with RTL “to see.” You will file fake bugs against the editor.

UK versus US English is the official inheritance example, not a second product: color / colour, 7/28/2010 versus 28/07/2010. Make UK a child of US (or the reverse) and change the phrases and the date format. Do not maintain two unrelated English packs.

Inheritance: the only way this stays maintainable

Official: languages can be arranged parent/child, “such that a child language may inherit all of the data from a parent language, and customize only those items that require change.” Full description lives in the styles inheritance section; the same mental model applies.

Practical trees that work:

Parent Child Why
US English (stock) UK English Spelling + date format
A complete Resource Manager Polish pack Polish (this board) Your board title, custom notices, add-on phrases
US English Staff glossary (not selectable) Experiment; prevent selection

The child exists so an upstream pack update does not wipe your sentences. When the RM author ships a new XML, you import onto the parent. The child keeps the phrases you customized. Official phrase inheritance: phrases inherit from the parent “unless they have been customized in the current language.”

Do not customize 4,000 phrases in the parent pack you imported. You will never be able to re-import cleanly. Customize in the child. Name the child after the board, not after the translator.

Add-ons add phrases. Those phrases land in the language they were written in (usually English) until you translate them. A child of Polish still shows English add-on strings until you phrase-edit them in that child. Budget that work per add-on, not “once for the site.”

Styles and languages are independent. Official: languages are like styles (collections, inheritance, a default). They are not coupled. A member can use the dark style variation with Polish phrases, or the light variation with English. Do not create Polish dark and English light as four languages. Create two languages and let 2.3 variations own colour. A style that hard-codes English into a template (instead of a phrase) will ignore the language pack. That is a template bug. Fix the template to call a phrase, then translate the phrase.

Emails are phrases too. Registration confirmations, password resets, watched-thread mails — the sentences are phrases. The wrapping HTML uses the default style for HTML email (a style option, official styles chapter, not a language option). Result: a Polish member should receive Polish sentences if their language is Polish and those phrases exist; the email colours follow the email style. If a reset mail goes out in English to a Polish UI user, you missed phrases, not the PWA language. Search Phrases for password or email on the child language and check Unmodified.

Do not invent an ACP “email language override” the cited pages do not document. The member’s language preference plus the phrase set is the mechanism.

Phrases: names, variables, the editor

Official definition: UI text is stored in snippets called phrases. XenForo calls a phrase rather than hard-coding a sentence.

Naming. Official: most phrases are named after their content. Please click the 'Save' button lives in something like please_click_the_save_button. When the text is too long, or the phrase is programmatic, the name describes the job: background_size_explain for the smilie editor help. When a phrase needs a variable, the name uses x or y: your_thread_x_has_been_updated.

Variables. Inside the phrase, official form is a word in curly braces:

Your thread, {name} has been updated.

Template syntax inserts the value. If you drop {name} in a translation, the board will still compile, and the member will not see which thread moved. Official upgrade note, next section, exists because of this.

Phrase editor. Official path: Appearance → Languages & phrases → Phrases.

  1. Select the language in the drop-down. Edit the child you created, not Master, not the imported parent if you can avoid it.
  2. Filter box at the top. Official: this filter searches all pages, not only the current screen.
  3. Click a phrase. You get the editable text and a copy of the Master value. Official: use the Master as the reference.
  4. Save stays in the editor. Save and exit returns to the list. Official: results are visible as soon as a page that uses the phrase is refreshed.

You will search by English meaning more than by phrase name. Type save and be prepared to page. Type the exact button label when you have it.

Mass-edit: Refine and translate

Official path for volume work:

  1. Refine and translate at the top of the phrase list.
  2. Enter filters if you need them.
  3. Set Phrase status to Unmodified only. Leave the other status options unchecked.
  4. Translate.
  5. Edit, Save per phrase without leaving the page.
  6. More at the bottom loads the next batch.

That is the official factory. Use it after you import a pack that is 90% done and you want the add-on leftovers. Do not use it to rewrite tone across the entire English parent.

Upgrades and customized phrases

Official, and kinder than templates: phrases contain simple data, so a customization is “highly unlikely” to break functionality after a XenForo upgrade, provided that all {variable} variables that existed in the original remain in your customized or translated version.

Rules you can hand a translator:

  • Never delete {name}, {count}, {title}, or any other brace token you did not add.
  • You may reorder tokens to match the target language grammar.
  • You may add punctuation around them.
  • If Master gained a new token after an upgrade, copy it into your phrase. The outdated-phrases tooling the ACP shows after upgrades is the queue. Treat it like outdated templates: merge, do not blindly keep.

Outdated templates are a style problem (see the 2.3 upgrade notes). Outdated phrases are a language problem. Do not merge them in the same sitting. You will miss a {variable}.

The PWA speaks one language

Official PWA chapter: Setup → PWA setup includes a Language control. “You must choose one of the languages installed on your forum to be the primary language for the progressive web app.”

That sentence is the multilingual tax. The installed app chrome — name, some system surfaces, the language you pick on that screen — is one language. Members can still switch the in-app UI if you allow multiple languages on the board, but the PWA record itself is not a per-user language pack. Official docs do not offer a second PWA language.

Pick the same language as Default language unless you have a written reason. A Polish default with an English PWA language is how home-screen icons and permission prompts feel “translated by a different company.”

Other official PWA requirements sit next to that selector and will block you if you ignore them while you are already in the screen:

  • HTTPS
  • Board title ≤ 12 characters or a Board short title
  • Square icons 192 and 512, PNG, ideally maskable
  • Push needs PHP 7.1+ with gmp, mbstring, openssl
  • iOS 16.4+: Add to Home Screen before push

This article will not rebuild the PWA performance story. It only needs you to treat Language as a one-value field. Revisit it when you change the site default.

What languages do not replace

They do not translate threads. There is no official “this node is French.” If you need a French section, create a node, write the node title in French, and moderate it in French. The buttons can still follow the visitor’s language pack.

They do not replace a locale user field. Staff who need to notice “this member prefers PL” still want a choice field with values you can criteria-match. The language preference XenForo stores for the UI is not documented on the custom-fields page as a criterion you should overload. Keep preferred_locale when you notify, promote, or search. Keep Appearance → Languages when you translate “Post reply.”

They do not localize the Board title in five ways. Board title is a site option. Phrases can wrap it in chrome (“Welcome to {board}”) but the option value is one string. A short PWA title is a second string, still one language.

They do not give you hreflang. Official language pages do not document an ACP hreflang map. A multilingual marketing site in front of the forum is a different property. Do not paste hreflang into PAGE_CONTAINER because a general SEO article said so.

They do not fix mixed-direction usernames. A Hebrew UI with English usernames will look like every other RTL product on the web. That is expected.

A worked bilingual board

Goal: public board, default Polish, English available, UK spelling not required, one add-on (a resource manager or similar) still half-English.

  1. Install XenForo. Confirm stock US English works.
  2. Download a 2.3-compatible Polish pack from Resource Manager translations-2-x.48. Import at Appearance → Languages.
  3. Create a child: Polish (board name), parent = the imported Polish. Prevent selection of the imported parent so members only see the child.
  4. Create a child: English (board name), parent = US English. Put board-specific wording here (welcome phrases, custom widget titles). Leave stock US as the hidden parent.
  5. Default language = Polish (board name).
  6. Language settings on the Polish child: locale pl_PL (or whatever the pack set), LTR, decimal , if that is the Polish standard the pack used, week start Monday, date format the pack used. Do not “improve” the date format on day one.
  7. Walk registration, a thread, a conversation, search, and the editor in both languages.
  8. Setup → PWA setup → Language = Polish (board name).
  9. Open Phrases on the Polish child. Refine and translate, unmodified only, filter by the add-on’s phrase prefix if it has one. Translate the member-facing leftovers. Leave ACP phrases in English if staff work in English — or translate them if they do not.
  10. Add a preferred_locale choice field (pl, en, other) only if you will target a notice. Do not add it “for SEO.”
  11. If you need a real English section, add a category and forums with English titles. Permissions stay the normal groups. Language packs will not hide a node from the other language.

Stop. Do not machine-translate 8,000 phrases in the parent. Do not run two defaults. Do not give guests four English variants.

Staff workflow that does not rot

  • One owner for the phrase children. Not “whoever has ACP.”
  • New add-on? Ticket: “phrase pass on Polish (board name).” Same as an outdated-template pass.
  • Custom widget titles and notice titles are not always phrases. A notice you typed in Polish stays Polish for English UI users. Write notices twice or write them in the language the audience shares. Official notices are content, not a language pack.
  • Node titles, prefixes, and thread titles are content. Translate them by having humans run those nodes, or leave them.
  • Export the child languages before you import a new parent XML.

Onboarding copy — the first notice, the suggested threads — should be written in the default language. An English-only welcome notice on a Polish default is a language bug you will blame on the pack.

Help pages, notices, and other things that are not phrases

Official help pages (Smilies, BB codes, Trophies, cookies, Terms, Privacy) are HTML you edit, plus a title and a URL portion. The chrome around them (“Help”, “Terms”) is phrases. The body is content. Translating the interface to Polish does not translate the Privacy essay. Edit the help page in the default language, or maintain a second help page (/help/privacy-en) if counsel actually needs two legal texts. Official help editor: URL portion becomes /help/{portion}. Do not expect the language switcher to swap the HTML body.

Notices, news posts, widget titles you typed as plain text, node titles, prefixes, custom thread field labels — same rule. If you did not put the string in a phrase, the language pack will not touch it. Official custom fields and thread fields have their own labels in their ACP forms; those labels are not documented on the language pages as automatically phrase-wrapped. Check the front end in the second language. If the label stays English, it is content. Translate it in the field’s ACP text or live with it.

Staff should write the Terms and Privacy help pages before they flip Default language. A Polish default with English legal pages is worse than an English default. The analytics article already told you to name Google in Privacy if you paste a Measurement ID. Do that edit in the language guests actually see.

Registration in a second language

Walk this in a private window with the guest language set to each shipped pack:

  1. Landing / forum list. Node titles are whatever you typed (content). Buttons are phrases.
  2. Register. Field labels and errors are phrases. Custom user fields you created show the labels you stored on the field. Official languages will not translate preferred_locale for you — that field is a choice list you wrote.
  3. Email confirmation. Phrase + email style, as above.
  4. First thread. Editor toolbar tooltips are phrases. The posted body is whatever they typed.
  5. PWA install prompt, if you ship one. Official PWA language = the one language you picked.

If step 2 shows half English, you have unmodified phrases or an add-on pack that was not translated. Refine and translate, Unmodified only, filter register or the add-on prefix. Do not switch the site default back and forth to debug; use the chooser on a test account.

RTL walkthrough (when you actually need it)

  1. Import a maintained RTL pack (do not flip US English to RTL).
  2. Confirm the language setting is right-to-left.
  3. Use a stock 2.3 style or a style that advertises 2.3 variations. Custom 2.1 skins fail here first.
  4. Test: forum list, thread view, inline editor, preview, visitor tab menus, date pickers, the login overlay, PWA install prompt.
  5. Fix extra.less in a child style, not in the language. Direction bugs are CSS.
  6. Keep the PWA language on that RTL language if it is also the site default.

If only 5% of members need RTL, still install it correctly. A broken RTL language you left selectable is worse than hiding it with the prevent-selection toggle until the style is ready.

Checklist

  • Pack version matches XenForo 2.3 (Resource Manager translations-2-x.48)
  • Imported pack is a parent; board-specific wording lives in a child
  • Prevent selection on unfinished or upstream-parent languages
  • Default language = the guest majority
  • Locale, LTR/RTL, decimal, week start, date format confirmed on each shipped language
  • Phrase edits keep every {variable}
  • Mass translate uses Unmodified only on the child
  • Add-on phrases budgeted separately
  • Setup → PWA setup → Language set to one installed language (usually the default)
  • PWA short title and icons still valid after the language pass
  • preferred_locale user field only if notices/promotions need it — it is not the language switcher
  • Node titles for real second-language sections are written by humans
  • Privacy / Terms help pages exist in the default language (stock help pages are content you must edit)

Takeaways

  • Official multilingual XenForo is languages + phrases + inheritance, not translated threads.
  • Appearance → Languages installs and hides packs. Default language is an Appearance option. The chooser is for members; the prevent-selection toggle is for you.
  • Settings (locale, RTL, decimal, week start, date) are official and wide-ranging. Do not casual-edit them.
  • Phrase editor: Appearance → Languages & phrases → Phrases. Master value on the right, {variables} stay in the translation.
  • Refine and translate + Unmodified is the official mass path.
  • Customize in a child. Re-import the Resource Manager pack onto the parent.
  • The PWA must pick one installed language. Official wording, not a suggestion.
  • A preferred_locale field is a targeting fact from the fields article. It is not a substitute for this system.

Translate the chrome. Moderate the content in the language it was written. That is a multilingual forum XenForo can actually run.

Related articles