DTLi18n — Reference Manual v1.1-46

Preface

Purpose

This manual describes what DTLi18n is, why it was created, and what it does. It is a functional and architecture reference. It deliberately contains no menu description, no command reference, and no step-by-step procedure.

DTLi18n browses, edits, and safeguards bilingual French/English localization catalogs, and assists a Python project's i18n compliance: verifying references between code and catalog, cross-checking an already internationalized project and correcting safe inconsistencies, and performing the initial conversion of a project that is not yet internationalized.

Intended audience

This document is intended for developers and maintainers of the NetDTL suite responsible for user-facing text, and for anyone who needs to understand DTLi18n's behavior before integrating it into a project or interpreting its reports.

Design principles

• Locality: catalogs, reports, and the learning base stay on the computer, with no dependency on a remote service.
• Caution by default: any operation that modifies source code or a catalog is preceded by a preview and a confirmation, and accompanied by a backup.
• Automation limited to what is safe: only deterministic, unambiguous corrections are applied automatically; everything else requires an explicit decision.
• Post-hoc verification: every migration or conversion is followed by a syntax check and a reference-resolution check, whose result appears in a report.
• No number reuse: a deleted key's number is permanently retired, never reassigned.
• Bilingual content: every catalog entry carries a French text and an English text; DTLi18n's own interface is in French.

Background

Origin of the need

A bilingual catalog maintained by hand drifts over time: keys get renamed or removed on the code side without the catalog following along, key numbers eventually collide, translations stay empty, and it becomes hard to know for certain whether a given key is still used anywhere in a project of any real size.

The problem looks different for a project that has never been internationalized: its user-facing text is hardcoded, mixed in with technical strings (logging, regular expressions, file names) that should not be translated, and converting everything by hand is slow and risks introducing syntax errors or references to keys that do not exist yet.

Problem addressed

DTLi18n was created to cover both halves of this lifecycle with the same safety guarantees: maintaining an existing catalog by keeping it synchronized with the code that uses it, and bootstrapping internationalization for a project that does not yet have it, without ever leaving the project in a state where a reference points to a missing key or the code no longer compiles.

Architecture

Overview

DTLi18n is organized around four processing families: direct editing of a catalog, analysis of the references between code and catalog, cross-project audit of an already internationalized project, and the initial conversion of a project that is not. All four share the same backup, preview, and reporting mechanism.

Components

File organization

Data model

i18n catalog

A catalog is a dictionary in which each key maps either to an object holding an fr text and an en text, or, in legacy catalogs, to a plain string interpreted as French text with an empty English text. DTLi18n accepts this dictionary as a Python literal or as a JSON file, and preserves the original format on save.

Key identification

The convention DTLi18n recognizes associates each key with an alphabetic prefix, a number, and an optional label separated by a hyphen or underscore (for example t0001_key_name). This number acts as a stable handle for direct navigation, duplicate detection, and numbering; a key that does not follow this format remains editable and searchable, but has no reference number.

Retired-number registry

When a key is deleted, its number is recorded in a permanent registry tied to the catalog. That number is never proposed again by numbering, which prevents a number already encountered in the project's history, a backup, or an earlier report from later coming to designate a different text.

Local learning base

DTLi18n keeps, in a local base, the decisions made on ambiguous strings during an audit or a conversion. These decisions are reused in later analyses to propose, with an explicit confidence level, an automatic classification of cases judged similar, without ever applying that classification without the user's control.

Features

Browsing and editing a catalog

DTLi18n can display an entire catalog without changing it, or open it in an editor that shows each key with its French and English text, allows navigating entry by entry or in blocks, searching by text or key, and editing each language's text independently. An entry can be left unchanged, replaced, or explicitly cleared.

Numbering and key migration

DTLi18n can rename every key in a catalog according to the numbered convention, with a chosen starting number, prefix, and numbering width. The rename is carried through to every reference found in the project's source files. The operation is preceded by a full preview of the renaming and its statistics, and is refused outright if duplicate numbers or syntax errors already exist in the project.

Safe key deletion

Deleting a key is refused as long as references to it remain in the analyzed project's source files. Once the deletion is confirmed with a reason, the key is removed from the catalog and its number is permanently recorded in the retired-number registry.

Project reference verification

DTLi18n can cross-check a catalog against a project's source files to list references to a key missing from the catalog, and catalog keys with no observable use in the code. This analysis distinguishes a direct, literal reference from an indirect or propagated use, and flags dynamic calls whose actual key cannot be determined with certainty; the absence of an observable reference is not presented as proof of non-use.

Cross-project audit of an internationalized project

DTLi18n cross-checks the catalogs and sources of an already internationalized project to detect inconsistencies — orphaned keys, broken references, duplicate numbers, no actually demonstrated language-selection mechanism — and assigns each one a confidence level. Inconsistencies for which a deterministic, unambiguous correction exists can be applied automatically after a single confirmation, with a prior backup. The others are turned into remediation texts meant to be handled individually, outside DTLi18n. An audit before correction and an audit after correction are both recorded in the same report.

Converting a non-internationalized project

DTLi18n detects user-visible strings hardcoded in a project's Python files, and classifies them into three categories: probably translatable, probably technical, or ambiguous. Each category can be included or excluded in bulk, or reviewed string by string. Selected strings receive a proposed key under the numbered convention and are used to build a new catalog along with the corresponding source-file changes, with a prior backup and a final check of syntax and reference resolution.

i18n maturity score

DTLi18n computes, for a project, a score and an overall internationalization status, based on whether internationalization is actually detected, the completeness of French and English translations, the share of keys whose use is observed in the code, the number of strings still hardcoded or ambiguous, and whether a language-selection mechanism is demonstrably present.

Internal reference

Internal modules

Robustness and integrity

• Any catalog change is preceded by a backup copy of the original file.
• Any source-file change (numbering, deletion, audit correction, conversion) is preceded by a backup of every affected file.
• Numbering and conversion are refused outright when existing Python syntax errors are present in the project.
• Deleting a key is refused as long as a reference to it remains in the source code.
• Every catalog or source-file write goes through a temporary file followed by a replace, and the result is re-validated syntactically before being kept.
• Unsaved translation changes block launching numbering and deletion, to avoid losing edits.

Appendices

Known limits

• Only keys following the prefix + number convention have a reference number; other keys remain editable but fall outside direct navigation, duplicate detection, and numbering.
• Reference detection relies on analyzing calls to explicitly named functions in the code; a key reached only through a fully dynamic, unresolved call is not counted as referenced.
• The absence of an observable reference for a key is not proof that it is unused.
• The audit only applies corrections explicitly marked as safe automatically; any other inconsistency requires individual handling.
• Classification of conversion candidate strings is a heuristic assisted by the local learning base; ambiguous cases require an explicit decision, at least the first time a pattern is encountered.
• DTLi18n does not automatically translate text from one language into another.

Versions and schemas

Glossary