# Manage translations

## Requirements

Qt Linguist tools are used to manage translations. Install them using your system package manager:

```bash
# On Ubuntu/Debian
sudo apt install qttools5-dev-tools

# On Fedora
sudo dnf install qt5-designer qgis-devel

# Or on newer systems with Qt6
sudo apt install qt6-tools-dev
```

## Quick Workflow (Recommended)

The project provides automated commands using `just` for translation management:

```bash
# Update translation files (extract translatable strings)
just trans-update

# Compile translation files (.ts to .qm)
just trans-compile
```

## Manual Workflow

If you prefer to run the commands manually or need more control:

### 1. Ensure proper environment

Always use `uv run` to ensure commands run in the correct virtual environment:

```bash
# Generate the plugin_translation.pro file
uv run python scripts/generate_translation_profile.py
```

### 2. Update .ts files

Extract translatable strings from source code:

```bash
# Using uv run (recommended)
uv run pylupdate5 -noobsolete -verbose dip_strike_tools/resources/i18n/plugin_translation.pro

# Or using just (simpler)
just trans-update
```

### 3. Translate text

Use Qt Linguist to translate your text or edit `.ts` files directly:

```bash
# Launch Qt Linguist for translation
linguist dip_strike_tools/resources/i18n/*.ts

# Or edit .ts files directly in your text editor
```

### 4. Compile translations

Convert `.ts` files to binary `.qm` files:

```bash
# Using uv run (recommended)
uv run lrelease dip_strike_tools/resources/i18n/*.ts

# Or using just (simpler)
just trans-compile
```

## Development Workflow Integration

Translation management is integrated into the development workflow:

```bash
# During development, after adding new translatable strings
just trans-update

# After translating, before testing
just trans-compile

# Run all development tasks including translations
just bootstrap-dev  # Sets up environment and compiles existing translations
```

## Notes

- **`pylupdate5`**: Extracts translatable strings from source code and updates `.ts` files
  - `-noobsolete`: Avoids removing obsolete translations (maintains translation history)
  - `-verbose`: Provides detailed output for debugging
- **`linguist`**: Launches Qt Linguist GUI for user-friendly translation editing
- **`lrelease`**: Compiles `.ts` files into binary `.qm` files for Qt applications
- **Git tracking**: The resulting `*.qm` files should not be tracked in git history since they're autogenerated binary files. The CI/CD pipeline handles generating and packaging them