> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nvaccess/nvda/llms.txt
> Use this file to discover all available pages before exploring further.

# Translating NVDA

> Guide for translating and localizing NVDA to different languages

Thank you for considering localizing NVDA to your language or improving an existing translation! NVDA's multilingual support depends on dedicated translators around the world.

<Note>
  To support multiple languages, NVDA must be translated and locale-specific data must be provided. This guide will walk you through the entire process.
</Note>

## Getting Started

### Join the Translation Community

Subscribe to these mailing lists:

* **[NVDA localisation mailing list](https://groups.google.com/a/nvaccess.org/g/nvda-l10n/about)** (read-only)
  * Monitors changes to symbols and character description files
  * Low traffic, only important updates
* **[NVDA translations mailing list](https://groups.io/g/nvda-translations)**
  * General conversations regarding translations
  * Ask questions and connect with other translators
  * Receive reminders before releases

### Important Dates

<Warning>
  Translators must ensure their translation is up to date during the beta period before each release for it to be included in the final release.
</Warning>

A reminder will be posted on the translation mailing list giving **two weeks notice** of the translation string freeze. Work submitted after this date will not be included in the upcoming release.

For more information, see the [Release Process page](https://github.com/nvaccess/nvda/blob/master/projectDocs/community/releaseProcess.md).

### Check Translation Status

View [Crowdin](https://crowdin.com/project/nvda) for an up-to-date report on translation status for all languages.

## Translation Workflows

NVDA translation is split between two platforms:

<CardGroup cols={2}>
  <Card title="Crowdin" icon="language">
    For NVDA interface and user documentation:

    * nvda.po (interface messages)
    * userGuide.xliff (User Guide)
    * changes.xliff (What's New document)
  </Card>

  <Card title="GitHub" icon="github">
    For locale-specific data:

    * characterDescriptions.dic
    * symbols.dic
    * gestures.ini
  </Card>
</CardGroup>

## Starting a New Localization

<Steps>
  <Step title="Subscribe to mailing lists">
    Subscribe to both mailing lists mentioned above to get help and advice from experienced translators.
  </Step>

  <Step title="Request translator access">
    Message the [translators mailing list](https://groups.io/g/nvda-translations) or [info@nvaccess.org](mailto:info@nvaccess.org) to request being added as a translator. Include:

    * Your Crowdin username
    * The languages you wish to translate
  </Step>

  <Step title="Set up translation tools">
    Choose your translation workflow:

    * Crowdin web interface (for quick translations)
    * Poedit desktop application (recommended for screen reader users)
  </Step>

  <Step title="Begin translating">
    Start with the NVDA interface messages (nvda.po), then move on to documentation and locale-specific files.
  </Step>
</Steps>

## Improving an Existing Localization

If you want to help with an existing translation:

1. **Contact the existing maintainer** - Discuss your suggestions and changes
2. **Agree on translations** - Work together on the best terms and translations to use
3. **Request maintainer status** - If a language is no longer maintained, you can request to become the new maintainer via the mailing list

To find out who maintains your language, email the translation mailing list.

## Files to be Localized

| File                          | Description                             | Platform | Required    |
| ----------------------------- | --------------------------------------- | -------- | ----------- |
| **nvda.po**                   | NVDA's interface messages               | Crowdin  | Yes         |
| **characterDescriptions.dic** | Names of characters in your language    | GitHub   | Yes         |
| **symbols.dic**               | Names of symbols and punctuation        | GitHub   | Yes         |
| **userGuide.xliff**           | The User Guide                          | Crowdin  | Recommended |
| **gestures.ini**              | Remapping of gestures for your language | GitHub   | Optional    |
| **changes.xliff**             | List of changes between releases        | Crowdin  | Optional    |
| **Add-ons**                   | Optional features users can install     | External | Optional    |

For detailed information on each file format:

* [Character Descriptions documentation](https://download.nvaccess.org/documentation/developerGuide.html#characterDescriptions)
* [Symbols documentation](https://download.nvaccess.org/documentation/developerGuide.html#symbolPronunciation)
* [Gestures documentation](https://download.nvaccess.org/documentation/developerGuide.html#TranslatingGestures)

## Translating with Crowdin

Crowdin is used for the main NVDA interface and user documentation.

### Creating a Crowdin Account

1. Create a [Crowdin account](https://accounts.crowdin.com/register?continue=%2Fproject%2Fnvda)
2. Message the [translators mailing list](https://groups.io/g/nvda-translations) or [info@nvaccess.org](mailto:info@nvaccess.org) to request translator access
3. Include your Crowdin username and languages you wish to translate

### Two Crowdin Workflows

<Tabs>
  <Tab title="Crowdin Web Interface">
    Translate strings directly in your browser.

    **Pros:**

    * Quick and convenient
    * No software to install
    * Real-time collaboration

    **Cons:**

    * May be inefficient for screen reader users
    * Accessibility limitations

    For instructions, read [Crowdin's documentation for translators](https://support.crowdin.com/for-translators/).
  </Tab>

  <Tab title="Poedit Desktop App">
    Download files, translate offline, and upload back to Crowdin.

    **Pros:**

    * Accessible to screen reader users
    * Work offline
    * More control over workflow

    **Cons:**

    * Requires setup
    * Extra steps for download/upload

    See [Translating with Poedit](#translating-with-poedit) below.
  </Tab>
</Tabs>

<Note>
  Due to accessibility issues, the translation approvals feature has been disabled in the NVDA project on Crowdin. All new strings are essentially auto-approved, but only translators specifically added to the project can add or change strings.
</Note>

### Translating with Poedit

Poedit is a desktop application commonly used for translations. It's fairly accessible and used by many blind and vision impaired translators.

#### Setting Up Poedit

<Steps>
  <Step title="Download Poedit">
    Download the latest Windows version from [poedit.net/download](https://poedit.net/download).
  </Step>

  <Step title="Install Poedit">
    Follow the on-screen instructions. Default options are sufficient.
  </Step>

  <Step title="Locate NVDA l10n utility">
    The NVDA l10n utility is required for safely downloading and uploading translation files.

    Included with NVDA from 2025.1beta1 onwards:

    * **Installed copies:** `c:\Program Files (x86)\nvda\l10nUtil.exe`
    * **Portable copies:** `l10nUtil.exe` in the root directory
  </Step>
</Steps>

#### Workflow

<Steps>
  <Step title="Download translation file">
    Use NVDA's l10n utility to download the translation file:

    ```bash theme={null}
    l10nUtil.exe downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
    ```

    **Example:**

    ```bash theme={null}
    l10nUtil.exe downloadTranslationFile fr nvda.po
    ```

    The first time, you'll be asked for an authorization token:

    1. Visit [your Crowdin settings API page](https://crowdin.com/settings#api-key)
    2. Create a Personal Access Token with at least the translations scope
    3. Paste it into the prompt
    4. It will be saved in `~/.nvda_crowdin` for future use

    <Tip>
      If multiple translators work on your language, save a copy of the downloaded file before translating. This allows l10nUtil to upload only your changes, avoiding conflicts.
    </Tip>
  </Step>

  <Step title="Translate with Poedit">
    Open the downloaded .po or .xliff file in Poedit:

    * You'll see a list of all strings to translate
    * Status bar shows: translated, untranslated, and fuzzy strings
    * Fuzzy strings are auto-translated and may be wrong
    * NVDA beeps on untranslated or fuzzy messages
    * Braille displays show a star for untranslatable messages

    **Useful shortcuts:**

    * `control+b` - Copy original string to translation field
    * `control+s` - Save your work
    * `control+shift+a` - View automatic comments (translator context)

    NVDA provides additional shortcuts described in the [User Guide](https://download.nvaccess.org/documentation/userGuide.html#Poedit).
  </Step>

  <Step title="Upload translation file">
    After translating, upload the file back to Crowdin:

    ```bash theme={null}
    l10nUtil.exe uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
    ```

    **Example:**

    ```bash theme={null}
    l10nUtil.exe uploadTranslationFile fr nvda.po
    ```

    **If you saved the original file:**

    ```bash theme={null}
    l10nUtil.exe uploadTranslationFile fr nvda.po --old nvda_old.po
    ```

    This uploads only your changes, preventing conflicts with other translators.
  </Step>
</Steps>

<Warning>
  Do not download/upload translation files via Crowdin's web interface or use Poedit's Crowdin cloud feature. These methods can corrupt xliff files. Always use NVDA's l10n utility.
</Warning>

## Translating the NVDA Interface

### Download the Interface File

* **Crowdin web interface:** Find "NVDA interface messages" file
* **Poedit workflow:** Download as `nvda.po`

```bash theme={null}
l10nUtil.exe downloadTranslationFile fr nvda.po
```

### Understanding Message Formatting

Messages may contain formatting strings:

| Format      | Meaning  | Example                              |
| ----------- | -------- | ------------------------------------ |
| `%d`        | Digit    | `%d percent` → "25 percent"          |
| `%s`        | String   | `subject: %s` → "subject: Important" |
| `%.2f`      | Float    | `%.2f seconds` → "5.25 seconds"      |
| `{keyword}` | Variable | `{color} on {backgroundColor}`       |

<Warning>
  Formatting strings must remain intact. Translate around them, not the format codes themselves.
</Warning>

### Shortcut Keys with Ampersands

Example: `&Rate`

The letter following `&` becomes a shortcut key. You can place the ampersand anywhere in your translation:

* English: `&Rate` (shortcut: R)
* French: `&Vitesse` (shortcut: V)

Try not to have duplicate shortcut keys in the same dialog.

### Plural Forms

Languages have different plural forms:

**English (2 forms):**

* Singular: "with %s item"
* Plural: "with %s items"

**Arabic (6 forms):**

* Zero, One, Two, Few, Many, Other

In Crowdin, use the "Form" section to set translations for each plural form.

In Poedit, use [object navigation](https://download.nvaccess.org/documentation/userGuide.html#ObjectNavigation) to access plural form tabs:

* Move to previous object from edit box: `NVDA+numpad4` (desktop) or `NVDA+shift+leftArrow` (laptop)
* Activate tab: `NVDA+numpadEnter` (desktop) or `NVDA+enter` (laptop)

If the number of plural forms for your language is incorrect, contact the [translators mailing list](https://groups.io/g/nvda-translations).

### Testing Interface Translation

<Steps>
  <Step title="Copy the .mo file">
    After saving in Poedit, copy `nvda.mo` to:

    ```
    nvdadir/locale/langcode/LC_MESSAGES/nvda.mo
    ```

    Where:

    * `nvdadir` = NVDA installation directory
    * `langcode` = ISO 639-1 language code (e.g., `en`, `es`, `fr`)
  </Step>

  <Step title="Change NVDA language">
    1. Restart NVDA
    2. Go to NVDA menu → Preferences → General Settings (or `NVDA+control+g`)
    3. Select your language from the list
    4. Restart when prompted
  </Step>

  <Step title="Verify translations">
    Your translated messages should now be heard or brailled in your native language (if your synthesizer/braille display supports it).
  </Step>
</Steps>

### Corrupted Translations

Incorrect formatting strings can cause NVDA to misbehave or crash.

**Protection measures:**

* Poedit + l10n utility: Validates translations before upload
* Crowdin web interface: Detects some problems (shows as QA issues)
* Pre-merge validation: Translations are checked before inclusion in NVDA builds

<Note>
  Subscribe to the [NVDA localisation mailing list](https://groups.google.com/a/nvaccess.org/g/nvda-l10n) to be notified about errors in interface translations. Error messages start with affected languages, e.g., "\[ab, cd\_EF]: Errors in interface translations".
</Note>

## Translating User Documentation

Documentation available for translation:

* **userGuide.xliff** - The NVDA User Guide
* **changes.xliff** - The What's New document

Both can be translated via:

* Crowdin web interface (locate the file and translate directly), or
* Poedit workflow (download, translate, upload)

### Understanding Markdown in Documentation

The English documentation is written in markdown. The xliff file contains translatable content from that markdown file.

**What's excluded:**

* Blank lines
* Hidden table header rows
* Structural lines without translatable content

**What's included in translator notes:**

* **Line:** Original line number in markdown
* **Prefix:** Structural markdown before content
* **Suffix:** Structural markdown after content

<Warning>
  Inline markdown syntax (links, inline code fences, table separators) must be kept intact when translating.
</Warning>

**Examples of inline syntax to preserve:**

* Links: `[link text](url)`
* Code: `` `code` `` or ` `` `
* Table columns: `|`

### Verifying Documentation Translation

Generate HTML from your xliff file to verify formatting:

```bash theme={null}
l10nUtil.exe xliff2html -t [userGuide|changes|keyCommands] <xliff file> <output html file>
```

**Example:**

```bash theme={null}
l10nUtil.exe xliff2html -t userGuide userGuide_fr.xliff userGuide_fr.html
```

Open the HTML file in a browser to review your translation.

## Translating on GitHub

Symbols, character descriptions, and gestures are translated via GitHub pull requests.

### Staying Updated

<Tabs>
  <Tab title="gestures.ini">
    Check the latest beta's changes for any new gestures added.
  </Tab>

  <Tab title="symbols.dic and characterDescriptions.dic">
    Subscribe to the [NVDA localisation mailing list](https://groups.google.com/a/nvaccess.org/g/nvda-l10n) to receive notifications when changes occur.

    Changes are relatively infrequent. Many releases may go by without changes.
  </Tab>
</Tabs>

### Translation Process

<Steps>
  <Step title="Be notified of changes">
    Receive notification via:

    * Mailing list (for symbols and character descriptions)
    * Beta release notes (for gestures)

    Email notifications include a diff showing what changed:

    * Lines prefixed with `+` are additions
    * Lines prefixed with `-` are removals
    * Lines prefixed with `@@` show location of changes
  </Step>

  <Step title="Find the file on GitHub">
    Navigate to your language's directory:

    ```
    https://github.com/nvaccess/nvda/tree/beta/source/locale/{lang}
    ```

    Replace `{lang}` with your language code (e.g., `en`, `fr`, `es`).

    Find the file you need to edit:

    * `symbols.dic`
    * `characterDescriptions.dic`
    * `gestures.ini`
  </Step>

  <Step title="Create file if needed">
    If the file doesn't exist, create it using the "add file" button:

    * **characterDescriptions.dic:** Copy desired contents from [English example](https://raw.githubusercontent.com/nvaccess/nvda/refs/heads/beta/source/locale/en/characterDescriptions.dic)
    * **symbols.dic:** Copy desired contents from [English example](https://raw.githubusercontent.com/nvaccess/nvda/refs/heads/beta/source/locale/en/symbols.dic)
    * **gestures.ini:** Start with an empty file, add gestures as needed

    Translate all content you copy.
  </Step>

  <Step title="Edit the file">
    1. Tab to the "edit file" button
    2. First time: GitHub will ask you to fork the repository - click "Fork this repository"
    3. **Important:** Ensure indentation uses tabs, not spaces

    To change indent mode in the editor:

    1. Press `NVDA+space` to switch to browse mode
    2. Press `shift+c` until you reach the "Indent mode" combo-box
    3. Press `enter` to activate
    4. Press `downArrow` to select "Tabs"
    5. Press `NVDA+space` for browse mode, then `e` to return to editor
    6. Press `enter` to focus the editor
  </Step>

  <Step title="Submit your changes">
    1. Press `control+s` or click "commit changes" button
    2. Update commit message: "Update \[filename] for \[language]"
    3. Press "Propose changes"
    4. New window opens with your proposal
    5. Feel free to ignore or delete the large template description
    6. Press "Create pull request"
  </Step>

  <Step title="Await feedback">
    NV Access will:

    * Review your changes
    * Provide feedback if needed
    * Merge when approved
    * Notify you when merged

    After merging, changes become available in [beta builds](https://download.nvaccess.org/snapshots/beta/) for testing.
  </Step>
</Steps>

## File Format Details

For detailed technical information about each file format:

* **characterDescriptions.dic:** [Developer Guide - Character Descriptions](https://download.nvaccess.org/documentation/developerGuide.html#characterDescriptions)
* **symbols.dic:** [Developer Guide - Symbol Pronunciation](https://download.nvaccess.org/documentation/developerGuide.html#symbolPronunciation)
* **gestures.ini:** [Developer Guide - Translating Gestures](https://download.nvaccess.org/documentation/developerGuide.html#TranslatingGestures)

## Getting Help

If you need assistance with translation:

* **Email:** [NVDA translations mailing list](https://groups.io/g/nvda-translations)
* **Technical issues:** [info@nvaccess.org](mailto:info@nvaccess.org)
* **General questions:** Ask on the mailing list - experienced translators are happy to help!

<Tip>
  Translation is a community effort. Don't hesitate to ask questions or collaborate with other translators for your language!
</Tip>

## Resources

* [Crowdin NVDA project](https://crowdin.com/project/nvda)
* [Poedit homepage](http://www.poedit.net/)
* [NVDA Developer Guide](https://download.nvaccess.org/documentation/developerGuide.html)
* [Release Process](https://github.com/nvaccess/nvda/blob/master/projectDocs/community/releaseProcess.md)