Best Practices when using Translations for Confluence Cloud
Concept
A page editor is completely free to choose which language macros to use - or not use - on any page. Nevertheless, it is advisable to write a concept with your team:
Which languages should be included on which types of pages or blog posts? For example, is it necessary to translate internal notes, or should the translations only be applied to public-facing content?
Should you create space templates (or global templates) that already include the language macros relevant to your company?
Will screenshots have to be included in various languages?
Are you using macros in the texts that need to be translated? More on that below ⤵️
Which workflow will be installed to ensure the translations are carried out and kept up-to-date?
Workflow
Work on your content in the original language until you are satisfied with its current state.
Separate sections with macros from those without macros (details see below ⤵️ ).
Place the original texts, images, etc., in a language macro.
Place Confluence & 3rd-party macros below the language macro, not in the language macro.
Add the second language macro below the first.
Copy screenshots, special formatting etc., from the original into the new language macro.
Only now, start translating the content itself.
How to deal with nested macros
Confluence Cloud has problems nesting one macro inside the other, and language macros are affected by this limitation. Specific Confluence macros like table of contents, excerpt, view-file, viewdoc, viewpdf etc, and many 3rd-party app macros cannot be placed inside language macros or cause errors. See the full documentation of limitations.
As a workaround, divide your Confluence page into sections that do not contain macros and those that do. You can enter as many language macros in the same language on the same page as you want. This will allow you to separate your content into sections and not use nested macros.
For sections that do not contain macros, you can insert the various language macros for the desired languages and fill them with the content (translations, images, etc.).
For a page section that only consists of a Confluence or 3rd-party macro, simply add that macro below or above the language macros, not inside of them.
Proceed with another language macro for the following page section containing only text and images.