DTLi18n — User Guide v1.1-46

Preface

Purpose of this guide

This guide explains how to use DTLi18n to browse and edit a bilingual French/English text catalog, migrate it to a numbered key convention, verify and audit a Python project's internationalization, and convert a project that is not yet internationalized. It covers the main menu, the interactive editor, the command-line options, and a set of common scenarios.

For a functional description of the tool, why it was created, and how it works internally, see the DTLi18n Reference Manual.

Intended audience

This guide is for developers and maintainers who use DTLi18n day to day to maintain a text catalog or move forward the internationalization of a NetDTL suite Python project.

Reminder: what DTLi18n is

DTLi18n browses, edits, and safeguards bilingual 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. This reminder is deliberately short; the why and the internal workings are covered in the reference manual.

A note on language

DTLi18n's console interface is in French. This guide describes the screens and prompts as they actually appear, with an English translation given the first time each one is introduced.

Getting started

Launching

DTLi18n launches in three ways:

• With no argument: opens the main menu, described below.
• With the path to an i18n file (DTLi18n path/to/catalog.py): opens the editor directly on that file.
• With the path to a project folder (DTLi18n path/to/project): analyzes the project directly and offers a conversion if it is not internationalized.

The --mode option specifies which action to perform on the given path; it is detailed in Non-interactive mode.

Key convention

DTLi18n recognizes keys in the format t0001_key_name: a prefix, a number, and an optional label. This number enables direct access via G, duplicate detection, and automatic numbering. A key that does not follow this format remains browsable and editable, but does not benefit from these functions.

Opening a file with no numbered keys

If the i18n file selected for editing contains no key in the numbered format, DTLi18n does not open the editor directly. It shows the recommended convention, a renaming example based on the file's first key, and offers two paths forward: T ("T : lancer l'assistant de numérotation" — launch the numbering wizard, see Number the keys), or Q ("quitter" — quit) with no change.

Main menu

The main menu, shown in French, offers five modes plus exit:

1. List a catalog's texts

Opens a file picker, then displays the entire chosen catalog — key, French text, and English text for each entry — without changing it, pausing every 20 entries. Useful for browsing or visually reviewing a catalog with no risk of accidentally modifying it.

2. Edit an i18n file

Opens a file picker, then opens the chosen catalog in the interactive editor described in Editor commands. If the file has no numbered keys, the warning described in Opening a file with no numbered keys is shown first.

3. Verify a project's internationalization

Opens a folder picker, then analyzes the chosen project: i18n status detection, translation completeness, share of keys whose use is observed in the code, strings still hardcoded, and an overall maturity score and status. If the project is already internationalized, the result is shown and the tool returns to the menu. If it is not, DTLi18n asks whether to prepare an FR/EN conversion; answering yes leads directly into mode 5.

4. Audit an internationalized project

Opens a folder picker, then cross-checks the chosen project's catalogs and sources to detect inconsistencies: orphaned keys, broken references, duplicates, no demonstrated language selection. An initial audit is shown; if safe corrections exist, DTLi18n offers to apply them after a single confirmation, with a backup. A second audit after correction is then shown, and a before/after JSON report is written at the project root. Remaining inconsistencies can produce remediation prompts, copyable to the clipboard for individual handling outside DTLi18n.

5. Convert a non-internationalized project

Opens a folder picker, then detects user-visible strings hardcoded in the chosen project and classifies them into three categories: probably translatable, probably technical, ambiguous. For each category, DTLi18n offers to include it in bulk, exclude it in bulk, or review each string individually; ambiguous strings are reviewed individually by default. A full summary is shown before any write; after confirmation, DTLi18n creates a new catalog, edits the affected source files, backs up every modified file, and writes a conversion report.

Editor commands

Once a catalog is open (mode 2, or a file passed on the command line), DTLi18n shows the current entry — its key, French text, and English text — along with the following command line, shown in French:

Navigation

↑ and ↓ move by one entry; PgUp/PgDn move by ten entries; Home and End go to the catalog's first and last entry.

Edit an entry (Enter or E)

Shows the current key's existing French and English text and prompts for new text in each language. Leaving a field empty keeps the existing text; typing =vide ("empty") clears it. The change is kept in memory only until saved with S.

Search (/) and go to a number or key (G)

/ searches for a number, an exact key, or French or English text containing the input, scanning the catalog from the current entry; N repeats the last search. G jumps directly to an entry by its number (as 42, 042, or t042) or its full key. A number or key can also be typed directly at the command prompt for immediate access.

Duplicates (D) and missing translations (M)

D lists key numbers used more than once in the open catalog. M lists keys whose French or English text is empty, up to 200 entries.

Unreferenced keys (R)

Asks for the project's root folder, analyzes it, then lists catalog keys that no reference found in the code uses. This check is simpler than V's: it does not distinguish indirect or dynamic uses.

Verify the project (V)

Asks for the project's root folder, then runs a finer analysis than R: references found, keys referenced in the code but missing from the catalog, and keys with no observable use, distinguishing direct uses from indirect or unresolved dynamic-call uses. If keys with no observable use exist, DTLi18n offers to list them on screen (L) or export them to a text file at the project root (E).

Number the keys (T)

Launches the numbering wizard: a summary of already-numbered and unnumbered keys, a choice of starting number (proposed automatically after the largest existing number, including retired numbers), prefix, and numbering width, then asks for the project's root folder. A full preview of the renaming is shown before any confirmation. The wizard is blocked if unsaved changes exist, if duplicate numbers exist, or if the project contains Python syntax errors.

Delete a key (X)

First analyzes references to the current key across the project; if references remain, the deletion is refused and their location is shown. With no remaining references, DTLi18n asks for a reason for the deletion, then an explicit confirmation. Once confirmed, the key is removed from the catalog and its number is permanently recorded in the retired-number registry.

Save (S) and quit (Q)

S saves the catalog to disk, after keeping a copy of the previous version in backup/. Q ends editing; if changes are unsaved, DTLi18n asks whether to save, discard the changes, or cancel exiting.

Non-interactive mode

Overview

DTLi18n accepts a path argument and a --mode option to run an action directly, without going through the main menu.

• File path, with no --mode or with --mode edit: opens the editor, like mode 2.
• File path with --mode list: lists the catalog without changing it, like mode 1.
• Folder path, with no --mode or with --mode verify: analyzes the project, like mode 3.
• Folder path with --mode convert: analyzes the project and directly offers conversion without asking for prior confirmation, like mode 5.
• Folder path with --mode audit: cross-project audit, like mode 4.

--version shows only DTLi18n's version number.

Command-line quick reference

Common scenarios

Quickly fixing an existing translation

1. Run DTLi18n path/to/catalog.py to open the editor directly.
2. Press / and type an excerpt of the text or the key to fix.
3. Press E and type the new text for the affected language(s).
4. Press S to save.

Migrating a legacy catalog to the numbered convention

1. Open the catalog for editing. If no key is numbered, DTLi18n shows the warning described in Opening a file with no numbered keys directly.
2. Press T to launch the numbering wizard.
3. Accept the proposed starting number, prefix, and width, or adjust them.
4. Point to the project root folder whose references need updating.
5. Review the preview, then confirm.

Safely deleting an obsolete key

1. Save any pending change with S: deletion is blocked otherwise.
2. Move to the key to delete, then press X.
3. If references remain in the project, remove them from the source code first, then run X again.
4. Give a reason, then confirm the deletion.

Checking that no key was forgotten after a development pass

Two levels of verification are available: R for a quick list of keys with no reference found, or V for a finer analysis distinguishing direct, indirect, and dynamic uses, with the option to export the result.

1. In the relevant catalog's editor, press V.
2. Provide the project's root folder if it is not already the one proposed by default.
3. Review references to a missing key first, if any: they indicate text used in the code but not defined in the catalog.
4. For keys with no observable use, press L to list them or E to export them before deciding on a deletion.

Auditing an existing i18n project and applying safe corrections

1. From the main menu, choose 4 and select the project folder.
2. Review the initial audit: detected inconsistencies, each one's confidence level, and the language selector's status.
3. If safe corrections are proposed, answer yes to apply them; a backup is created automatically.
4. Review the audit after correction, then the JSON report written at the project root.
5. For remaining inconsistencies, copy a remediation prompt to the clipboard to handle it individually.

Internationalizing a French project for the first time

1. From the main menu, choose 5 and select the project folder, or choose 3 and answer yes to the conversion prompt.
2. For each detected string category, decide on bulk inclusion, bulk exclusion, or individual review; ambiguous strings are reviewed one by one by default.
3. Review the full summary before any write: the catalog to be created, the number of included strings per category, the affected files.
4. Confirm to trigger writing the new catalog, editing the source files, and creating the conversion report.

Messages and blocking situations

Common blocking situations

Appendices

Main menu quick reference

Editor command quick reference

File locations