Languages
OINK uses Hugo’s multilingual model without adding directory conventions.
Configure a languages block. Put each translation beside its original in
the same directory, with a language suffix in its filename. This page explains
how to convert a single-language site to a bilingual site. It also covers two
common problems: resource ownership and heading anchors.
Enabling a second language
This site uses the configuration above. The four fields have these functions:
labelis the name shown in the language picker, written in that language’s own script:简体中文, notChinese.localeis the standard language tag. It supplies<html lang>,hreflangalternate links, and Open Graph metadata.weightdecides both language order and the picker’s cycle order, lowest first.paramscontains per-language overrides. If a key is absent here, it inherits the global value with the same name. Date formats usually need per-language values.
The default language has no path prefix, such as English at /docs/….
Each other language has a prefix, such as Chinese at /zh/docs/…. To also
prefix the default language, add defaultContentLanguageInSubdir: true. This
changes every site URL. For a live site, configure redirects at the same time.
File naming and resources
Put each translation beside its original, with a language suffix. Hugo uses the shared base filename to identify them as language versions of one page:
content/docs/
- install.mdEnglish
- install.zh.mdChinese
- _index.md
- _index.zh.md
Page bundles work the same way: index.md and index.zh.md in one directory.
In a page bundle, every language shares resources without a language suffix. A resource with a language suffix belongs only to that language.
content/docs/install/
- index.mdEnglish page
- index.zh.mdChinese page
- topology.webpavailable to both languages
- screenshot.zh.webpavailable to the Chinese page only
When you reference a suffixed resource in the body, write its name without
the suffix: . Hugo resolves it for the current
language.
If a bundle contains only index.zh.md, with no English counterpart, its
unsuffixed resources do not belong to the Chinese page. They belong to the
default language, which has no page in that bundle. Each resource therefore
needs the .zh. suffix. This site’s Chinese page bundles under docs/ use
that structure.
What needs translating:
- Translate:
title,description, summaries, menu labels, tag names, image alt text, callout bodies, and reader-facing shortcode parameters. - Keep identical: dates,
weight, aliases, and any metadata affecting routing. A mismatch makes the sidebar order differ between languages. - Do not translate: commands, configuration keys, filenames, URLs, version numbers, product names, shortcode names.
Per-language configuration
Three things live outside content/ and need one copy per language.
Menus are written under their own language:
The identifier must match across languages. Command palette quick links and
search result grouping both use it. For complete menu configuration, see
Navigation and menus.
Home page data uses the language files data/home/en.yaml and
data/home/zh.yaml. If the current language has no file, it falls back to
en.yaml. A single-language site needs only data/home.yaml. See
Home and landing pages.
Interface strings: the theme ships 32 complete interface catalogs. These
use the 31 locale filenames supported by Docsy, plus generic zh. Every
catalog contains all 235 OINK messages in its native language. No catalog
depends on generated English fallback blocks. zh and zh-cn use Simplified Chinese, while zh-tw uses
Traditional Chinese. The exact locale and placeholder contract is recorded in
Architecture. To change a
string, create a file of the same name under the site’s own i18n/ and write
only the keys you override:
The current Hugo baseline accepts locale: zh alongside regional Chinese
catalogs. The concrete locale: zh-CN shown above also works; no older-Hugo
locale workaround is required.
Untranslated fallback and the language picker
The language picker icon is a link. Click it to select the next language by
weight. After the last language, it returns to the first. Hover or focus it
to expand a menu of all languages. On a touch screen, a tap switches language
directly without expanding the menu. A bilingual site switches between its
two languages with one click.
The menu always lists every configured language, whether or not the current page is translated:
- If the target language has a translation, open that page;
- If the target language has no translation, open its home page.
The home page fallback avoids a 404. However, readers may not notice that they moved to the home page. A bilingual site should enforce “every page has a counterpart” as a constraint. Do not depend on the fallback.
This fallback belongs to the language picker. Since OINK 1.2.0, this fallback is separate from SEO: the hreflang links list
only the current page and actual translations. Each blog pagination page has
its own canonical URL, and later pages omit language alternates. See
canonical URLs and language alternates.
If no Chinese page exists, the Chinese site has no version of that page. Its sidebar, search index, and paging order omit the page.
Search indexes also apply per language. A search from a Chinese page matches only Chinese content. Queries support separated CJK terms, mixed languages and technical identifiers. See Search.
Heading anchors must align
Hugo derives IDs from heading text. A Chinese heading therefore produces a
Chinese ID. The links /docs/install/#prerequisites and
/zh/docs/install/#前置条件 point to corresponding sections with different
anchors. Cross-language deep links, contents links, and in-page jumps then break.
Set the original heading’s ID explicitly on the translated heading:
Follow these two rules:
- Read the ID from the HTML the English page renders. Do not derive it from heading text. Inline code, badges, or shortcodes can produce different IDs.
- Corresponding pages must have the same heading count, order, and IDs. If a translation needs an extra section, give it an independent stable ID. It must not conflict with an English ID.
This documentation site’s translation checker
compares source structure and rendered heading IDs. The following command runs
in the oink.pgsty.com checkout; the script is not part of a normal consumer site:
Before adapting it to your CI, change its fixed content scopes and EN/ZH file
conventions. It locates source files relative to the script itself; --public
only chooses the rendered output directory. For a manual check, compare the
heading IDs in a representative translated pair’s generated HTML.
Add explicit English {#id} anchors when you create a page. This requires less
work than adding them later.
Duo view
Set params.ui.compare: true to let readers open a page alongside one of its
translations:
On Docs, Book, and blog pages that have a published HTML translation on the same
origin, OINK adds an Open duo view button beside the page actions.
Readers can also launch Duo View from the command palette or press
B when keyboard navigation is on (try it on this page); pressing
B again returns to the page. The current page stays on the
reading-start side while the other pane loads the selected translation; if a
page has more than two languages, readers can switch the target language from
the toolbar menu. Below 900px, the view switches to a single-pane layout with
a language toggle bar.
The Sync Scroll switch keeps both panes aligned at the same section by
matching the heading IDs described above, so consistent {#id}
anchors give the best result. If some headings have no counterpart, or the two
pages share none, the reader estimates the position between matching headings or
from overall reading progress. An orange ! beside the switch then says which;
hover over it, focus it, or tap it to read the note. If heading IDs are
duplicated or appear in a different order across languages, Sync Scroll
turns off automatically while leaving both panes open for independent reading.
Enabling the duo view does not generate extra pages at build time. The reader
fetches the two existing HTML pages inside same-origin frames only when a reader
opens it. Pages without a translation, drafts, language-home fallbacks, and
translations hosted on another domain are excluded automatically. To disable
the duo view for a specific language—both as a host page and as a comparison
target—set compare: false under languages.<lang>.params.ui.
Before enabling it in production, check two details:
- Custom analytics snippets in
hooks/head-end.htmlrun inside each pane frame unless guarded withwindow.OinkComparePane; see Analytics. - Your Content Security Policy must allow
frame-src 'self', and the server must not sendX-Frame-Options: DENYorframe-ancestors 'none'; see Content Security Policy.
Right-to-left languages
Declare the writing direction under the language:
The <html dir> value follows this setting. The theme also loads Bootstrap’s
RTL stylesheet. Theme CSS uses logical properties throughout, such as
margin-inline-start instead of margin-left. This automatically mirrors the
layout. Use logical properties in site CSS too. Otherwise, RTL can position
elements incorrectly.
Verify
-
Build from your site’s root. Confirm that output exists for both languages. These paths assume English at
/and Chinese at/zh/. Adjust them for your language settings. Check indexes only if local search is enabled: -
Check
hreflangand canonical URLs against SEO behavior.hreflanglists only actual translations; each blog pagination page has its own canonical URL, and pages after page 1 omit language alternates. -
On a translated page, expand the language picker and select the other language. Confirm that the same document opens. Repeat on an untranslated page. Confirm that the target language’s home page opens instead of a 404.
-
Search the same concept once in each language and confirm both return results.
-
Compare heading IDs in a translated page pair. Before adding this check to CI, adapt the documentation-site script as described above. Do not run it unchanged against a different content tree.
Related
- Search — per-language indexes and CJK queries
- Navigation and menus — per-language menus and where the picker sits
- Home and landing pages —
data/home/<lang>.yaml - Writing pages — how to write explicit heading IDs
- Analytics and SEO — how
hreflangand the sitemap are consumed by search engines