Index your code with Devin
DeepWiki

0xJacky/nginx-ui

Menu

Translation System Architecture

Relevant source files

Purpose and Scope

This document describes the translation system architecture used in Nginx UI, specifically focusing on how vue3-gettext integrates with the Vue 3 frontend, the structure and format of translation files, and how translations are extracted from source code and loaded at runtime.

For information about the translation workflow using Weblate and how translators contribute, see Weblate Integration. For a complete list of supported languages and their completion status, see Supported Languages.

System Overview

Nginx UI uses vue3-gettext, a Vue 3 port of the GNU gettext internationalization system, to manage translations across 14 languages. The system follows a standard gettext workflow: translatable strings are marked in source code, extracted to template files, translated in PO (Portable Object) files, and loaded at runtime based on the user's language preference.

Architecture Diagram

Sources:

Translation File Structure

Directory Layout

Sources:

PO File Format

PO (Portable Object) files are the standard format for gettext translations. Each PO file contains metadata in the header and a series of message entries mapping source strings (msgid) to translated strings (msgstr).

PO File Structure

SectionDescriptionExample
HeaderMetadata including language, translator, plural forms"Language: zh_CN\n"
Message EntrySource string and translationmsgid "Add Site" msgstr "添加站点"
ContextSource code location reference#: src/routes/modules/sites.ts:26
Plural FormsHandling singular/plural translationsmsgid_plural "Certificates Status"
Variable InterpolationDynamic content in strings"%{name}, %{email}, %{caDir}"

Example PO File Entry

#: src/language/generate.ts:37 msgid "[Nginx UI] ACME User: %{name}, Email: %{email}, CA Dir: %{caDir}" msgstr "[Nginx UI] ACME 用户：%{name}，邮箱：%{email}，CA 目录：%{caDir}" #: src/routes/modules/sites.ts:26 src/views/site/site_add/SiteAdd.vue:74 msgid "Add Site" msgstr "添加站点" #: src/views/certificate/components/AutoCertManagement.vue:67 #: src/views/site/site_edit/components/Cert/Cert.vue:58 msgid "Certificate Status" msgid_plural "Certificates Status" msgstr[0] "证书状态"

Sources:

PO File Header

Each PO file begins with a header containing critical metadata:

Header FieldPurpose
LanguageISO 639-1 language code + optional region code
Plural-FormsFormula for plural form selection
Last-TranslatorTranslator contact information
PO-Revision-DateLast modification timestamp
Content-TypeCharacter encoding (always UTF-8)

Sources:

Source Code Integration

Marking Translatable Strings

Vue3-gettext provides several methods for marking strings as translatable in Vue components and TypeScript files:

MethodUse CaseExample
$gettext('string')Simple translation$gettext('Add Site')
$ngettext(singular, plural, n)Plural forms$ngettext('Certificate Status', 'Certificates Status', count)
interpolate(string, vars)Variable substitutioninterpolate('%{name}', {name: 'John'})
$pgettext(context, string)Contextual translation$pgettext('navbar', 'Home')

Source Code References in PO Files

Each message entry includes comments indicating where the string appears in source code:

#: src/routes/modules/sites.ts:26 #: src/views/site/site_add/SiteAdd.vue:74 msgid "Add Site" msgstr "添加站点"

This enables:

  • Traceability: Translators can see context
  • Maintenance: Unused strings can be identified
  • Updates: Source changes trigger retranslation

Sources:

Generated Translation Strings

Special translation strings for dynamic messages (like certificate operations) are pre-defined in a dedicated file:

Sources:

Translation Extraction Process

Extraction Workflow

Extraction Configuration

The extraction process identifies translatable strings by scanning for:

  1. Vue Template Directives: v-translate, translate-context, translate-plural
  2. Composition API Calls: $gettext(), $ngettext(), $pgettext()
  3. TypeScript/JavaScript: String literals passed to translation functions
  4. Comments: Special markers like gettext: for translator notes

Sources:

Runtime Loading and Language Switching

Language Loading Flow

Supported Locales List

The LINGUAS file defines all available languages:

en zh_CN zh_TW fr_FR es de_DE ru_RU vi_VN ko_KR tr_TR ar uk_UA ja_JP pt_PT
Locale CodeLanguageRegion
enEnglishGeneric
zh_CNChineseSimplified (China)
zh_TWChineseTraditional (Taiwan)
fr_FRFrenchFrance
esSpanishGeneric
de_DEGermanGermany
ru_RURussianRussia
vi_VNVietnameseVietnam
ko_KRKoreanSouth Korea
tr_TRTurkishTurkey
arArabicGeneric (RTL support)
uk_UAUkrainianUkraine
ja_JPJapaneseJapan
pt_PTPortuguesePortugal

Sources:

Plural Forms Handling

Different languages have different rules for pluralization. The Plural-Forms header defines the formula for each language.

Plural Forms Examples

LanguagePlural-Forms FormulaDescription
Englishnplurals=2; plural=(n != 1);0 is plural, 1 is singular
Chinesenplurals=1; plural=0;No plural distinction
Russiannplurals=2; plural=(n != 1);Complex slavic rules
Arabicnplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 ? 4 : 5;Six plural forms

Plural Message Entry Example

In languages with multiple plural forms (like Russian or Arabic), additional msgstr[n] entries are required:

Sources:

Variable Interpolation

Translation strings can contain variables that are substituted at runtime using the %{variable} syntax:

In Vue components, variables are passed as an object:

Common Variable Patterns:

PatternUsageExample PO Entry
%{name}User/resource names"Auto-renewal enabled for %{name}"
%{start}-%{end}Ranges"%{start}-%{end} of %{total} items"
%{error}Error messages"Failed to execute, error: %{error}"
%{groupName}Resource groups"Includes nodes from group %{groupName}"

Sources:

Context and Comments

Source Code Context References

PO entries include references to source file locations where each string is used:

#: src/components/NgxConfigEditor/NgxServer.vue:144 #: src/components/NgxConfigEditor/NgxUpstream.vue:97 #: src/language/curd.ts:19 msgid "Add" msgstr "添加"

This shows the string "Add" appears in three different files, helping translators understand context.

Translator Comments

Some entries include special comments for translators:

#: src/views/nginx_log/components/IndexingSettingsModal.vue:217 msgid "* Performance metrics measured on Apple M2 Pro (12-core) with 32GB RAM. Actual performance may vary based on your hardware configuration." msgstr "* 性能指标基于 Apple M2 Pro （12 核）和 32GB 内存测得。实际性能可能因您的硬件配置而异。"

Sources:

Summary

The Nginx UI translation system architecture consists of:

  1. Storage Format: GNU gettext PO files for each of 14 supported languages
  2. Extraction: Automated scanning of Vue components and TypeScript files
  3. Runtime: vue3-gettext plugin loading translations based on user locale
  4. Features:
    • Plural forms handling for different languages
    • Variable interpolation with %{variable} syntax
    • Context-aware translations with source code references
    • Integration with Weblate for collaborative translation (see 4.3)

All translation files are located in app/src/language/ with the master template at app/src/language/messages.pot and language-specific translations in subdirectories like app/src/language/zh_CN/app.po app/src/language/es/app.po etc.

Sources: