Languages

Arc CMS has two translation systems: one for the public site, where visitors read content in the language of the URL, and one for the admin interface, where each person picks their own language. They are independent, so a site that publishes in Hindi can be run in English.

What it is

Arc CMS ships English and Hindi for both. An app can give its members, and people on the sign-in page, a language Arc CMS does not ship, such as German, while the admin keeps English and Hindi: see Member languages.

URLs

The default language keeps unprefixed URLs. Every other language gets its code as a prefix, with the same slug:

/articles/my-post       default language
/hi/articles/my-post    Hindi

The URL alone decides the language. A prefix only works for an enabled language that is not the default, so /en/articles does not exist on an English site.

How content is translated

A translation is a document beside the entry, holding only the fields that differ:

arc_articles/{id}                     the default language
arc_articles/{id}/translations/hi     Hindi: only what is translated

A page in Hindi is the default entry with the Hindi fields laid over it, so anything untranslated shows the default text and a half-translated page still works. Title, body, summary, SEO title, meta description, text and rich text fields, and the words inside repeating fields (such as info cards and gallery captions) can be translated. The URL, cover image, tags, dates, numbers, images and dropdown values are shared by every language. Untranslated entries still appear in list pages, with their default-language card.

Turn it on or off

Languages are always on and are not a switchable feature. A site with one language shows no language switcher and no prefixes. Content translation lives in the content editor, so it goes with Content.

Set it up

Add a public language

For example French (fr):

1. Enable it. Admin, Settings, Localization, Add a language, then Save Languages. Pick it from the list, or choose Other and enter a code such as sw or pt-br. A code that a page already has as its address, such as pay when the app has /pay, is refused. The editor offers a French tab straight away. The same page sets the default language and the order of the switcher.

2. Translate the words in templates. Create src/custom/site/strings/fr.json, using public/_site/strings/hi.json as the list of keys. A partial file is fine: a missing key keeps the English.

3. Translate content type names. Content, Content types, edit each type and use its French tab: name, singular name, description and custom field labels.

4. Translate the content. Open each entry, pick the French tab, fill in what matters and publish. Save and Publish apply to every language at once.

5. Deploy the website. Run npm run deploy and choose Website or Everything, so fr.json is on the live site. The deploy then publishes every page again, and each content page, list page and the home page gains its French version. Publishing an item later republishes that item's pages; Republish website (Content, Content types) rebuilds them all.

Optional, a translated home page: write src/custom/site/home.fr.html as a whole page in French; without it, home.html is published in French through its data-arc-t keys. Either way the home page exists in every enabled language, at /fr. See Build your home page.

Removing a language stops new pages being published for it. Pages already on Hosting stay until the content is republished or unpublished.

Add an admin language

1. Create src/assets/i18n/fr.json: copy src/assets/i18n/en.json without _conventions and translate the values. It must have every key.

2. Add { code: 'fr', label: 'Français' } to ADMIN_LANGUAGES in src/app/core/i18n/admin-languages.ts.

3. Add the import to TRANSLATIONS in src/app/core/i18n/translation.loader.ts, written out in full (a bundler only follows an import it can see), and to CUSTOM_TRANSLATIONS when src/custom/i18n/fr.json exists.

4. Register the locale in src/app/core/i18n/admin-locale.provider.ts so dates and numbers format correctly.

5. Add the file to the list in src/test/i18n-parity.spec.ts, then run the tests.

Use it

Words in public templates

For short text in templates, the header and the footer, mark the element and leave the English inside it. The English is the fallback.

<span data-arc-t="read_more">Read Article</span>
<input data-arc-t-attr="placeholder:search_placeholder,title:search_title">
<span data-arc-t="min_read">{{ readTime }} min read</span>
<span data-arc-t="seats_left" data-arc-t-params='{"count": 5}'>5 seats left</span>

Then add each key to the language's strings file, src/custom/site/strings/{lang}.json, a flat JSON object of "key": "text" pairs. Arc CMS ships one for Hindi (public/_site/strings/hi.json); an app's file for a language Arc CMS ships is merged over it key by key, so it holds only the keys the app adds or rewords, and keeps receiving Arc CMS's new keys. For any other language the app's file is the whole list. A file for the default language works the same way on every page in that language, static pages included, and in the app; Arc CMS ships none, so the wording written in the HTML stands until a site adds one. An empty value counts as untranslated. Values may use {{ }} template values ("min_read": "{{ readTime }} मिनट का पठन"), because strings are applied before the template is filled, or values from data-arc-t-params ("seats_left": "{{ count }} सीटें बाकी"). data-arc-t replaces everything inside the element, so keep icons outside it. The same three attributes work on published pages and in the Angular app. Published pages bake the strings in at publish time, and the functions cache the strings files for five minutes. The website walkthrough is Write a strings file.

The language switcher

The site header's <arc-language-switcher> becomes the switcher: markup on published pages, a component in the app. It offers only the languages the current page exists in, never every enabled language, so it never links to a missing page. A page in the app declares its languages with LocalizationService.languageVariants.set([...]) and clears it with set(null) when it leaves; a page that sets nothing shows no switcher. The switcher stores the visitor's choice in localStorage as arc-lang, but nothing reads it: a visitor landing on / gets the default language.

Links keep the visitor's language

The header and footer are one file for every language, so their links are written root-relative (/articles) and rewritten with the page's prefix: by prefixAnchorHrefs in functions/src/shared/language-links.ts on published pages, and by renderSiteFragment in src/app/pages/page.parts/site-fragment.ts in the app, which also applies the strings (src/app/core/i18n/apply-strings-dom.ts). A fragment can follow a language of its own instead of the page's (its language option, with strings from UiStringsService.load()): the sign-in panel does, in the language a member chose (see Member languages). Content templates build prefixed links with {{ langPrefix }} and {{ url }}.

Only addresses that exist in every language take the prefix (isLocalizedPath): the home page, search, and the list and item pages of a content type with public pages. Sign-in, the admin, the member area, an app's own pages, static pages and files exist once, so /signup stays /signup on a Hindi page. The publish functions read the public content types with publicContentTypeSlugs (functions/src/shared/public-content-types.ts), the app with PublicContentTypesService (src/app/core/site/public-content-types.ts); until the app has the list, its header leaves links unprefixed.

In the app, /{lang}/{type} matches only a public content type (publicContentTypeGuard), and any other address under a language prefix redirects to the same address without it (languageRedirect in src/app/guards/language.guard.ts), so a stray /hi/signup lands on /signup.

The language routes come before the app's own routes, so every address passes them, and they never make a page wait for the server when they need not (languageRouteGuard):

• A first segment that cannot be a language code, such as signup or admin, or that a route with a literal path already uses, such as an app's /pay, is passed on at once. A language code is 2 or 3 letters with an optional region, such as de or pt-br.
• Any other first segment is checked against the list this browser kept from its last read of Settings/localization, and the list is read again in the background. If the fresh list changes the answer for the page on screen, the page opens again.
• Only a first visit, with no list kept, waits for the read, and only for an address such as /de that could be a language and that no route uses. A single-language site, once its list is kept, never waits.

So the language routes can only claim a first segment that is a language code, enabled, not the default, and not used by any route. The Localization settings page refuses a code that a route uses, and npm run dev and npm run build warn when an app page's address is a language code in the catalogue (scripts/vite-language-routes.ts).

What search engines see

Each published page sets <html lang> (and dir="rtl" for a right-to-left language) and, when it exists in more than one language, one <link rel="alternate" hreflang> per language plus x-default for the default. The sitemap lists the same alternates. See SEO and discoverability. Search indexes each language separately and searches the language being viewed; see Search.

Admin interface text

Each person picks a language in the page header. It is saved on their user record and in the browser, so it follows them between machines and shows without a flash of English. Dates and numbers follow the new language from the next page load.

Keys live in src/assets/i18n/en.json first: common.* for words used everywhere (Save, Cancel, table chrome), admin.nav.* for the menu, admin.{area}.* per admin page, user.* for the member area. Name keys by role, not by text: common.actions.save. After editing en.json, regenerate the typed key list:

npm run i18n:keys

This writes src/app/core/i18n/translation-keys.ts. src/test/i18n-parity.spec.ts fails when you forget, when a translation misses a key or has one English does not, or when ADMIN_LANGUAGES offers a language with no file. At run time a missing key falls back to English.

Keep a sentence in one key, with {{ params }} and any markup inside the value (rendered with [innerHTML]), so a translator can reorder it.

Extend it

An app adds its own admin words, and rewords core ones, in src/custom/i18n/en.json and src/custom/i18n/hi.json. Each is laid over the core file key by key when the language loads:

{ "custom": { "nav": { "lessons": "Lessons" } }, "admin": { "nav": { "users": "Parents" } } }

Put the words an admin sees in both files. A test checks the ones it can tell are admin words, the labels of your admin menu items and admin menu changes and the core admin words you reword, and that hi.json has no key en.json lacks. Words only members see need Hindi only when Hindi is offered to members (Member languages); a missing one shows in English. Give a custom menu item a labelKey from these files (see Change the admin menu). Custom keys are not in the generated key list, so use them through the transloco pipe or TranslocoService.translate().

For a website, new public words are new data-arc-t keys in your templates and strings files (above).

What it stores

There are no language Cloud Functions or Storage paths: the publish queue builds one page per language the entry has.

Who can do what

See Users and roles.

Troubleshooting

For a website walkthrough, see Publish in more than one language.