Skip to content

Languages

Add a language and keep translations beside their originals. Configure menus and interface strings per language. Use matching heading anchors across 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

hugo.yml
defaultContentLanguage: en

languages:
  en:
    label: English
    locale: en-US
    weight: 1
    title: OINK
    params:
      description: A Hugo theme for engineering docs
  zh:
    label: 简体中文
    locale: zh-CN
    weight: 2
    title: OINK
    params:
      description: 为工程而设计的 Hugo 文档主题
      time_format_default: 2006年1月2日
      time_format_blog: 2006年1月2日

This site uses the configuration above. The four fields have these functions:

  • label is the name shown in the language picker, written in that language’s own script: 简体中文, not Chinese.
  • locale is the standard language tag. It supplies <html lang>, hreflang alternate links, and Open Graph metadata.
  • weight decides both language order and the picker’s cycle order, lowest first.
  • params contains 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: ![Screenshot](screenshot.webp). 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:

hugo.yml
languages:
  zh:
    menus:
      main:
        - identifier: docs
          name: 文档
          pageRef: /docs
          weight: 20

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:

i18n/en.yaml
ui_search: Search the docs

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.

A missing translation is never filled in with the original

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:

install.zh.md
## 前置条件 {#prerequisites}

Follow these two rules:

  1. 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.
  2. 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:

node scripts/check-doc-translations.mjs --public public

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:

hugo.yaml
params:
  ui:
    compare: true

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.html run inside each pane frame unless guarded with window.OinkComparePane; see Analytics.
  • Your Content Security Policy must allow frame-src 'self', and the server must not send X-Frame-Options: DENY or frame-ancestors 'none'; see Content Security Policy.

Right-to-left languages

Declare the writing direction under the language:

hugo.yml
languages:
  ar:
    label: العربية
    locale: ar
    direction: rtl
    weight: 3

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

  1. 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:

    hugo --printPathWarnings
    ls public/index.html public/zh/index.html
    ls public/offline-search-index.*
  2. Check hreflang and canonical URLs against SEO behavior. hreflang lists only actual translations; each blog pagination page has its own canonical URL, and pages after page 1 omit language alternates.

    # Replace with an actual generated page in your site.
    PAGE=public/zh/docs/getting-started/index.html
    test -f "$PAGE" && grep -o '<link[^>]*hreflang[^>]*>' "$PAGE"
  3. 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.

  4. Search the same concept once in each language and confirm both return results.

  5. 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.