Перейти к основному содержимому

ADR: Internationalization Policy

  • Status: Accepted by Andrei Ganiushkin andrey@ganyushkin.ru
  • Date: 2026-06-27
  • Authors: Andrei Ganiushkin andrey@ganyushkin.ru
  • Related issues: -

Context​

The Netgap project must be understandable to Russian-speaking and English-speaking users, developers, operators, external integrators, regulators, and auditors. At the same time, different product layers have different language requirements: code, logs, and engineering interfaces must remain compatible with international practice and legacy event collection systems, while official operational and certification documentation for the Russian market must be available in Russian.

A hybrid internationalization policy must be established to define the supported languages, the default language for each product layer, naming rules for bilingual documentation, and localization requirements for user interfaces.

Decision​

The project supports two languages:

  • Russian (ru);
  • English (en).

The project adopts a hybrid language selection model by layer.

English is used as the primary language for the engineering layer:

  • source code, names of variables, functions, modules, APIs, and technical comments in code;
  • technical logs, including output to syslog, journald, Loki, ELK, SIEM, and similar systems;
  • audit events intended for machine processing, correlation, search, and regular parsing;
  • CLI flags, argument names, machine-readable error codes, and messages intended for engineers and administrators;
  • architecture documents and ADRs when they relate to the open part of the project.

Russian is used as the primary language for the Russian regulatory and customer-facing layer:

  • official operational documentation for Russian customers;
  • documentation for the Ministry of Digital Development Registry, FSTEC, FSB, and other certification or conformity assessment procedures;
  • administrator and user guides, technical specifications, product passports, security assignments, and similar documents;
  • legal documents, security policies, data processing policies, and contractual materials intended for the Russian market when legislation or contractual requirements require Russian.

Bilingual support is mandatory for documentation and user-facing materials that are used simultaneously by external developers and Russian users or customers.

Regular documentation uses the ru and en language suffixes with dot separators before the file extension:

  • architecture.ru.md;
  • architecture.en.md;
  • operator-guide.ru.md;
  • operator-guide.en.md.

README files in repository directories must be available in both languages and use the same naming principle unless the file is the standard root README.md:

  • README.ru.md;
  • README.en.md.

An exception applies to standard repository files: the standard file is stored without a language suffix, and localized variants use suffixes. The only standard files without suffixes are:

  • README.md;
  • CONTRIBUTING.md;
  • CHANGELOG.md;
  • LICENSE.

For README.md, CONTRIBUTING.md, and CHANGELOG.md in the repository root, the primary language of the suffixless file is English, because these files are entry points for GitHub, external developers, and the international engineering community:

  • README.md — English, README.ru.md — Russian;
  • CONTRIBUTING.md — English, CONTRIBUTING.ru.md — Russian;
  • CHANGELOG.md — English, CHANGELOG.ru.md — Russian.

A separate exception applies to the LICENSE document: the license's primary language is English.

  • LICENSE — the primary English license text;
  • LICENSE.ru, LICENSE.ru.md, or LICENSE_ru — the Russian translation, if maintained by the project.

CLI interfaces of programs must use English by default for flags, arguments, system errors, and engineering messages. Help messages in the CLI may be in Russian. Web interfaces must support both languages.

Technical logs and audit events must be emitted in English. This reduces the risk of encoding issues in legacy systems, simplifies regular parsing, event correlation, error search, and integration with international observability tools.

Russian-language explanations for operators must be provided in documentation, runbooks, error references, or UI, not in machine-processed technical log and audit text.

Considered Alternatives​

Alternative 1: English only​

  • Pros: code cleanliness; simple integration with GitHub and the international community; correct log parsing; convenient engineering error search; lower risk of encoding issues in SIEM, ELK, syslog, and other systems.
  • Cons: insufficient for Russian regulatory and customer requirements; operational and certification documentation for the Ministry of Digital Development, FSTEC, FSB, and the public sector must be in Russian.
  • Reason for rejection: the project must comply with Russian market and certification requirements, so English alone is insufficient.

Alternative 2: Russian only​

  • Pros: convenient for Russian-speaking customers and regulators; reduces the cost of preparing official documentation for Russia.
  • Cons: critical risk of encoding and technical log parsing issues; isolation of the project from the international engineering community; reduced code accessibility for external audit and contributors; worse indexing and searchability of technical information.
  • Reason for rejection: the project cannot rely only on Russian even if the Russian market is primary, because the engineering layer of the project must remain English-language and compatible with industry tools.

Alternative 3: Hybrid layer-based model​

  • Pros: code, logs, and engineering interfaces follow international practice; official Russian documentation covers the requirements of Russian customers and regulators; the repository remains understandable on GitHub; the risk of encoding and log parsing issues is reduced.
  • Cons: higher maintenance cost; changes require synchronization between the English engineering layer and Russian operational/regulatory documentation.
  • Reason for selection: the hybrid model best balances engineering compatibility, Russian market requirements, certification, and project openness.

Alternative 4: All documents always use ru and en suffixes​

  • Pros: the most uniform file naming scheme.
  • Cons: conflicts with GitHub, Cargo, and other tools' expectations for standard files such as README.md, LICENSE, CONTRIBUTING.md, and CHANGELOG.md.
  • Reason for rejection: standard documents must remain available under their conventional suffixless names.

Consequences​

Positive​

  • The expected default language is defined for each product layer.
  • Code, CLI, technical logs, and audit use English as the language most compatible with engineering tools.
  • Official Russian documentation covers the requirements of Russian customers, the Ministry of Digital Development Registry, and certification procedures.
  • English and Russian become mandatory supported languages for documentation where required.
  • Standard documents retain the names expected by external tools and platforms.

Negative​

  • Documentation maintenance effort increases: changes must be synchronized between Russian and English versions.
  • User-facing CLI messages and documentation will require localization infrastructure or a synchronized translation process.
  • Temporary discrepancies between language versions may occur during active development.

Risks and Mitigations​

  • Risk: Russian and English documentation diverge in meaning.
    • Mitigation: update both language versions in the same change or explicitly record translation debt.
  • Risk: new documents are created in only one language or with an incorrect suffix.
    • Mitigation: add a CI check for naming and language-pair availability for documentation where applicable.
  • Risk: Russian-language messages appear in technical logs and audit events.
    • Mitigation: enforce English for logs and audit during code review, in logging guidelines, and through automated checks where possible.
  • Risk: official Russian documentation lags behind English-language changes in code and README.
    • Mitigation: update Russian documentation as part of the release checklist and explicitly record translation debt.

Acceptance Criteria​

  • The ADR records the supported languages ru and en.
  • The hybrid language selection model by product layer is recorded.
  • English is recorded as the primary language for code, technical comments, engineering CLI, technical logs, and audit events.
  • Russian is recorded as the primary language for official operational, legal, and certification documentation for Russia.
  • Regular documentation uses the ru or en dot-separated language suffix before the extension.
  • README files in directories use the README.ru.md and README.en.md format.
  • Standard suffixless files are limited to README.md, CONTRIBUTING.md, CHANGELOG.md, and LICENSE.
  • For README.md, CONTRIBUTING.md, and CHANGELOG.md, the English variant is stored without a suffix, and the Russian variant uses the ru suffix.
  • For LICENSE, the English variant is stored without a suffix, and the Russian translation uses the ru suffix or the existing project name LICENSE_ru.
  • CLI flags, arguments, and engineering messages use English;
  • Help messages in the CLI may be in Russian;
  • Web interfaces must support both languages.
  • Technical logs and audit events are emitted in English.

Verification​

The correctness of the decision is verified by documentation review and subsequent automated checks:

  • check that Russian and English versions exist for documentation where required;
  • check ru and en suffixes with dot separators;
  • check that the list of standard suffixless files is limited to README.md, CONTRIBUTING.md, CHANGELOG.md, and LICENSE;
  • check that README.md, CONTRIBUTING.md, and CHANGELOG.md are English, and Russian variants use the ru suffix;
  • check that LICENSE is English, and the Russian translation uses the ru suffix or the existing project name LICENSE_ru;
  • check that CLI flags, arguments, and engineering messages use English;
  • check that technical logs and audit events use English;
  • check that official Russian documentation exists for Russian operational, legal, and certification scenarios.

References​

  • ADL/adr-template.md
  • README.md
  • README.ru.md
  • CONTRIBUTING.md
  • CHANGELOG.md
  • LICENSE
  • LICENSE_ru