How to assemble multilanguage publications

We just updated DoX CMS to version 8.5. This came with a new feature that you can use to publish documents with content in more than one language. In this piece, I will discuss considerations related to first implementing this feature. At this time, this feature only supports PDF publications through either the default compiler or DocRaptor. You implement it separately for each publication in the Edit Publication menu. If you will use sets of languages other than all languages in your environment, you must also first define those language groups. See below for details.

In addition to the basics for how to assemble these multilanguage publications, I will discuss available settings for them. DocRaptor requires you to also use style sheets to implement such details because page headers and footers as well as page numbers in publications done with DocRaptor are determined through style sheets. The default compiler uses the settings in the system itself for them. However, I will also address how to add styles to the general parts of publications like this in general.

The steps to use multilanguage publications

Follow these instructions to publish multilanguage publications. You must also change your style sheets to accommodate them but the instructions for this are separately available below.

Language groups

Language groups are another new feature in DoX CMS which is currently only used with multilanguage publications. A language group is an ordered set of languages. It determines which languages a multilanguage publication included and the sequence in which they are included. Everyone can also use a language group which includes all languages in their environment in alphabetical sequence.

You will find language groups under the Control Translations tool in the new Language Groups view. Use this view to add new language groups, to edit them, and to remove them.

You must give names to new language groups. You must then add languages in them and put them in sequence. This menu is similar to the Edit Topic Tree menu, except you cannot drag and drop languages in the language group. You also cannot add a hierarchy to them. Instead, you add a sequence to a language group when you drag and drop languages in the language group to their positions.

In the future, language groups will likely have other uses. Currently, they remove the need to define such groups of languages each time when a publication has content in more than one language. You can select the used language group in the Publish menu in the same way as a language.

Edit a publication template

Most of the work to implement multilanguage publications occurs in the Edit Publication menu. You must define these details for such publications here but even when you do, you can still choose to publish that content in only one language.

The first step here is to select the Publish Language Group Details field. The menu will then show the other details that you can control:

1. Language Group: Select the default language group to use.
2. Outer Cover Page: Select the cover page for the whole publication. This cover will always be the selected topic in the active language.
3. Outer Back Cover Page: Select the back cover pae for the whole publication. This cover will always be the selected topic in the active language.
4. Page Numbers: Determine whether page numbers continue through the whole publication or start again for each language when you use the default PDF compiler.
5. Add Group ToC: Determine whether the publication will have a shared table of contents for content in different languages or not.
6. Group ToC Content: Determine the details of the shared table of contents if it is included. This table of contents can show either of the different languages and the pages at which their content starts, or the full table of contents for each language.
7. ToC Before Each Language: Determine whether each language will have its own table of contents before its other content.

This way, you can have multilanguage publications with, for example, only a set of outer cover or both outer covers and language-specific covers inside. You can also decide to include language-specific tables of contents and a shared table of contents that only shows language names. Another alternative is to only have the shared table of contents which then shows the contents in each language in full. You can use a style sheet to add details such as the names of languages before their content to such shared tables of contents.

Publish

The Language Setting field in the Publish menu lets you decide whether the publication includes one language or a set of languages.

When you select Specified Language, the Publish menu will show the usual list of languages. Select the publication’s language from this list. The default value is the active language.

When you select Specified Language Group, the Publish menu will show a list of language groups. Select the language group that the publication uses from this list. The default value is the selected value for the Language Group field in the Edit Publication menu. This will also hide publishing variables in the Publish menu. This occurs because they are processed differently in multilanguage publications. If you usually determine the values for some publishing variables when you publish the content, you must instead do so in the Edit Publication menu for multilanguage publications.

You can still use the Preview command to view the identifiers in the publication template with the browser’s Inspect command. Only the parts related to multilanguage publications will have new identifiers.

Multilanguage publications and style sheets

Implementing multilanguage publications requires you to include new rules and potentially change others in your style sheets. For example, you must use a style sheet to specify page numbers for DocRaptor publications. I will discuss such details related to style sheets below. The solutions that I propose must be adapted for your needs, though.

I will discuss both the identifiers for the new sections added to multilanguage publications and some DocRaptor-related implementations for the details that you control through the Edit Publication menu in the default compiler.

New sections

These are the identifiers for the new sections used only by multilanguage publications. You can add the rules for these sections in your defailt style sheets because these sections are not present in publications with only one language. If you must change other parts of a style sheet, you should perhaps use different styles for publications with one language or more than one language, respectively. You can still separate the changes related to multilanguage publications in their own style sheet to manage styles easier.

This is a list of the identifiers for new sections and related explanations:

• .langContentWrapper: These are the sections for each language in a DocRaptor publication.
• .langGroupFullTocWrapper: This is a shared table of contents which includes all content in each included language.
• .langGroupTocWrapper: This is a shared table of contents with only the names of included languages.
• [langID= tunniste=””]: These are the parts related to a given language in a shared table of contents. They use the identifiers for those languages as their values.
• .outerBackCoverPageWrapper: This is an outer back cover.
• .outerFrontCoverPageWrapper: This is an outer front cover.

For example, you should add page breaks before the parts related to different languages to have each of them start on a new page.

The identifiers related to the various tables of contents also let you modify their layouts by, for example, having the parts related to different languages on different pages and by adding the names of those languages before them. This requires you to use ::before pseudo-elements with those language names to elements with different langID values except when the elements before them have the same langID values. Find a language-specific example implementation here:

.tocline[langID="en"]::before {
    content: "English";
    display: block;
    break-before: page;
}

.tocline[langID="en"] ~ .tocline[langID="en"]::before {
    content: none;
    break-before: none;
}

.toccontent {
    break-before: none;
}

You must repeat the language-specific parts of this implementation for each included language. Since you can only use count-based selectors such as :first-child with element types, you cannot rely on them for classes or attributes. This is why the implementation first adds the rules to each element with the specified attributes and then removes them from each element immediately after a similar element.

Changes for DocRaptor publications

DocRaptor requires that the changes that multilanguage publications entail be done in a style sheet with CSS. You can only use this method to control these details in sich publications even if you will have access to more options for it.

Page Headers and Footers

Multilanguage publications involve new sections which may require their own page headers and footers. Because content in different languages will be in sequence, you may need to update the page headers and footers between languages. Your page headers and footers get added in the same positions in each language using the values for those languages. As such, the default implementation may not need changing. Meanwhile, shared parts must have their own page headers and footers. When you add them, make sure that they will not accidentally also continue to other parts.

For this, you should specify page groups for shared covers and the shared table of contents. Each of them may have its own page group or they may share one. You can also include these parts in the language groups that language-specific parts use if the page headers and footers between them will remain the same. The identifiers for these sections are listed above. You specify page groups with the command ‘page: name’. All the pages which include content that matches your selector will belong in a page group with that name. You can then use that page group’s name in page selectors.

You must also determine which files the shared parts use for their page headers and footers in the Edit Style menu. These parts now have their own fields in this menu. You add page headers and footers to them in the same way as to any other part of a publication. Because these parts always use the active language, so do their page headers and footers. If the same page headers and footers suit both these and the language-specific sections, you can use them. However, you must still add them to the shared parts.

Page numbers

You cannot add page numbers directly in the files for page headers and footers for DocRaptor. You must add them separately on top of those files. The continuity of page numbers is determined by where you start the count or reset it, and which page groups show that page number. The implementations shown below show examples for how you can either reset page numbers for each language or keep them continuous across the whole document, including shared parts.

Language-specific page numbers

Language-specific page numbers require you to reset page numbers at the start of each language’s section. In principle, the rules already in use in your style sheets may have this effect. Page numbers require you to specify where the count begins, and those points also always reset the count. If each language has them, the count starts again for each of them. If this is not the case, though, you can have separate page numbers for each language like this:

.langContentWrapper {
    counter-reset: page 1;
    break-before: right;
}

The model presented above starts page numbers from the start of each language and makes sure that each language starts from a right-hand page. As such, I do not recommend it if each language has its own covers, for example. Alternatively, you may start at page 0 rather than 1 if each language includes a cover page.

Please not how this implementation requires you to remove other rules that define where page numbers start from multilanguage publications. You can do this by adding the condition ‘:not(.langContentWrapper *)’ to the last part of the selector(s) for your usual rule(s), for example. You should replace the asterisk with the identifier for that last part of the selector. This works because .langContentWrapper only occurs in multilanguage publications and thus never in publications with just one language.

Continuous page numbers

Continuous page numbers in multilanguage publications require you to only start the count once and making sure that it never resets.

The examples below are related to different models for this. You should combine either of them with the method to prevent the default page numbering method from resetting page numbers in multilanguage publications which I presented above. In the first example, page numbers start from the shared table of contents regardless of its implementation. In the second example, page numbers start where the first language’s section starts.

.langGroupTocWrapper, .langGroupFullTocWrapper {
    counter-reset: page 1;
}

.langContentWrapper {
    counter-reset: page 1;
    break-before: right;
}

.langContentWrapper ~ .langContentWrapper {
    counter-reset: none;
}