Using ltext2id | Qt Linguist Manual

- Qt 6.11
- Qt Linguist Manual
- Using ltext2id
- Qt 6.11.1 Reference Documentation

Using lcheck ◦ Translators

# Using ltext2id

The `ltext2id` command line tool converts a project that uses text-based translations to use ID-based translations. It scans the project tree, updates source code to call the ID-based translation APIs, and adjusts the related `TS` files accordingly. In the case of any failed conversions, the source will be annotated with `//ltext2id error:` at the failed locations.

Note: Make a full backup (or work on a clean Git branch) before running `ltext2id`. The tool modifies source files and `TS` files in place.

For best results, include both the sources and the `TS` files in the project root you pass to the tool so that updates stay consistent between code and translations.

## ltext2id syntax

     ltext2id [options] [project-root]

Where:

- `options` means one or several ltext2id options.
- `project-root` is the directory to process recursively.

To view the latest help, enter:

     ltext2id -help

### ltext2id options

Option | Action
--- | ---
`-help` | Display up-to-date help information and exit.
`-no-labels` | Do not generate labels for ID-based translations. By default, message contexts are used as labels so that entries keep a similar visualization in Qt Linguist.
`-sort-messages` | Sort messages in a context alphabetically in TS files.
`-source-utf16` | Treat source files as UTF-16 encoded (default: false).
`-quiet` | Suppress progress output.
`-only-meta-id` | Only suggest IDs by inserting meta strings; do not perform the actual transformation to ID-based calls.
`-no-auto-id` | Do not auto-generate IDs when meta-string IDs are missing. Translation function calls without meta IDs are ignored.
`-version` | Display the version of `ltext2id` and exit.

## Examples

### Convert a project to ID-based translations

Run the tool at the project root. The source code and `TS` files under that directory are updated in place.

     ltext2id path/to/project

### Generate only ID suggestions (no code changes)

Use `-only-meta-id` to inject meta-string ID suggestions without rewriting calls to the ID-based API. As a result, the translation calls are annotated by '//~ meta-id <id>' (cpp) meta string specifying the suggested IDs (meta ID).

     ltext2id -only-meta-id path/to/project

### Disable label generation

Prevent label generation if you do not want contexts mirrored as labels in Qt Linguist:

     ltext2id -no-labels path/to/project

### Avoid auto-generated IDs

Skip auto-generation for calls missing meta IDs, i.e., IDs already specified using the meta string '//~ meta-id <id>' (cpp):

     ltext2id -no-auto-id path/to/project

### Work with UTF-16 source files

If your sources are UTF-16 encoded, enable the option:

     ltext2id -source-utf16 path/to/project

## Exit status

`ltext2id` returns a non-zero exit code on failure (for example, when it encounters an unrecoverable error while transforming files). Inspect the in-place source annotations marked with `//ltext2id error:` to fix the remaining issues.

Using lcheck ◦ Translators