Skip to main content
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.
To support multiple languages, NVDA must be translated and locale-specific data must be provided. This guide will walk you through the entire process.

​
Getting Started

​
Join the Translation Community

Subscribe to these mailing lists:

​
Important Dates

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.
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.

​
Check Translation Status

View Crowdin for an up-to-date report on translation status for all languages.

​
Translation Workflows

NVDA translation is split between two platforms:

Crowdin

For NVDA interface and user documentation:
  • nvda.po (interface messages)
  • userGuide.xliff (User Guide)
  • changes.xliff (What’s New document)

GitHub

For locale-specific data:
  • characterDescriptions.dic
  • symbols.dic
  • gestures.ini

​
Starting a New Localization

1

Subscribe to mailing lists

Subscribe to both mailing lists mentioned above to get help and advice from experienced translators.
2

Request translator access

Message the translators mailing list or [email protected] to request being added as a translator. Include:
  • Your Crowdin username
  • The languages you wish to translate
3

Set up translation tools

Choose your translation workflow:
  • Crowdin web interface (for quick translations)
  • Poedit desktop application (recommended for screen reader users)
4

Begin translating

Start with the NVDA interface messages (nvda.po), then move on to documentation and locale-specific files.

​
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

FileDescriptionPlatformRequired
nvda.poNVDA’s interface messagesCrowdinYes
characterDescriptions.dicNames of characters in your languageGitHubYes
symbols.dicNames of symbols and punctuationGitHubYes
userGuide.xliffThe User GuideCrowdinRecommended
gestures.iniRemapping of gestures for your languageGitHubOptional
changes.xliffList of changes between releasesCrowdinOptional
Add-onsOptional features users can installExternalOptional
For detailed information on each file format:

​
Translating with Crowdin

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

​
Creating a Crowdin Account

  1. Create a Crowdin account
  2. Message the translators mailing list or [email protected] to request translator access
  3. Include your Crowdin username and languages you wish to translate

​
Two Crowdin Workflows

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.
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.

​
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

1

Download Poedit

Download the latest Windows version from poedit.net/download.
2

Install Poedit

Follow the on-screen instructions. Default options are sufficient.
3

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

​
Workflow

1

Download translation file

Use NVDA’s l10n utility to download the translation file:
l10nUtil.exe downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
Example:
l10nUtil.exe downloadTranslationFile fr nvda.po
The first time, you’ll be asked for an authorization token:
  1. Visit your Crowdin settings API page
  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
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.
2

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.
3

Upload translation file

After translating, upload the file back to Crowdin:
l10nUtil.exe uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
Example:
l10nUtil.exe uploadTranslationFile fr nvda.po
If you saved the original file:
l10nUtil.exe uploadTranslationFile fr nvda.po --old nvda_old.po
This uploads only your changes, preventing conflicts with other translators.
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.

​
Translating the NVDA Interface

​
Download the Interface File

  • Crowdin web interface: Find “NVDA interface messages” file
  • Poedit workflow: Download as nvda.po
l10nUtil.exe downloadTranslationFile fr nvda.po

​
Understanding Message Formatting

Messages may contain formatting strings:
FormatMeaningExample
%dDigit%d percent → “25 percent”
%sStringsubject: %s → “subject: Important”
%.2fFloat%.2f seconds → “5.25 seconds”
{keyword}Variable{color} on {backgroundColor}
Formatting strings must remain intact. Translate around them, not the format codes themselves.

​
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 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.

​
Testing Interface Translation

1

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)
2

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
3

Verify translations

Your translated messages should now be heard or brailled in your native language (if your synthesizer/braille display supports it).

​
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
Subscribe to the NVDA localisation mailing list to be notified about errors in interface translations. Error messages start with affected languages, e.g., “[ab, cd_EF]: Errors in interface translations”.

​
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
Inline markdown syntax (links, inline code fences, table separators) must be kept intact when translating.
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: 
l10nUtil.exe xliff2html -t [userGuide|changes|keyCommands] <xliff file> <output html file>
Example: 
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

Check the latest beta’s changes for any new gestures added.

​
Translation Process

1

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
2

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
3

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
  • symbols.dic: Copy desired contents from English example
  • gestures.ini: Start with an empty file, add gestures as needed
Translate all content you copy.
4

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
5

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”
6

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 for testing.

​
File Format Details

For detailed technical information about each file format:

​
Getting Help

If you need assistance with translation:
Translation is a community effort. Don’t hesitate to ask questions or collaborate with other translators for your language!

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us