Getting started
The whole idea in one sentence:
One macro = one language. You put several in the same page, and each reader only sees theirs.
Your first bilingual page, in five minutes
- Create a page and give it a title. It is shared by every language — see the limits.
- Insert the macro: type
/and pick Language macro, or use the editor's+menu. - Choose its language. The settings panel opens with the language list already showing. Pick one, then Save.
- Write your text inside the macro, exactly as you would anywhere in Confluence.
- Add the second language: insert another macro, set it to your second language, and write the translation.
- Publish.
Under the page title you will now see Select language. That is where a reader switches.
Check the result
Open the page in view mode. You see one language only — yours, if it is on the page. Click Select language to switch: the page reloads in the chosen language, and the address does not change.
That is exactly what your readers will see.
What a reader sees
They configure nothing. Their language is picked automatically, in this order:
- the language they chose themselves on this page, if they did;
- their Atlassian account language — the normal case;
- the language marked as the page default;
- failing that, the first language on the page.
The advice worth passing on to your teams: set your language in your Atlassian profile. Everything then falls into place with no clicks, on every page.
The switcher under the title is for the exceptions — reading in another language, or when yours is not on this page. The choice is remembered for that page only.
The two macro settings
Both are optional. A macro with only its language set works perfectly.
Use this language as the page default
This only comes into play third. It applies when the reader has chosen no language for this page and their Atlassian account language is not available on it.
In other words it never overrides a reader's choice, nor their profile language: it is a safety net, not an imposed preference.
You are not required to set one. Without it, the first macro on the page plays that role, which is usually what the author intended. Only one macro should carry the setting; if several do, the app tells you.
Show the language label when viewing
Displays a flag and the language name above the content. On by default.
Turn it off if the visual marker gets in the way. It never appears in exported documents either way.
Messages you may see
They appear in the Select language panel, in edit mode as well as view mode. None of them blocks saving or publishing — they are signals, not errors.
| Message | What is happening | What to do |
|---|---|---|
| A language macro has an unrecognized language | A macro's language is no longer among those offered. Nobody will see that macro. | Open its settings and pick a language from the list |
| More than one macro is set to the same language | Two macros share a language. Only one will show. | Change one of them, or delete the duplicate |
| More than one language is marked as the default | Several macros claim the default role. | Keep the setting on one only |
| A language macro has no content yet | A macro is empty. The reader concerned sees a page with nothing on it. | Write the translation, or remove the macro meanwhile |
| This page has more than 3 languages configured | A marker, not an error. | Nothing required — see whether all these languages belong on this page |
Good practice
Keep the same language order across pages. Your authors edit and review several; a stable order saves them hunting.
Put your organisation's most common language first. It is the fallback when a reader's language is unavailable.
Translate the text, not the structure. Identical headings, lists and tables across languages make discrepancies obvious at a glance when updating.
Warn before removing a language. Deleting a macro moves the affected readers to the default language, with no notice on their side.
A change in one language notifies everyone watching the page, and shows in its history. That is normal Confluence behaviour, and it surprises people at first.
One thing to know before you start
Creating and configuring a macro needs a mouse. In the Confluence editor, a macro's edit button cannot take keyboard focus. That limit belongs to the editor and affects every app of this kind.
Reading is fully keyboard-operable: reaching the switcher, browsing the languages, choosing one.
The details, and the rest of what is worth knowing, are in the limits.