Help and documentation
Everything runs in your browser. This page explains each step, what the app does with your files, and what to do when something goes wrong.
What it is
Translate Your App – Business translates the resource files of .NET, .NET MAUI, WPF, WinUI and Windows applications. A resource file (.resx or .resw) holds the text your application shows, one entry per string. The app reads the file in your source language, keeps a work file per target language in the industry-standard XLIFF format, sends each string to your own Azure AI Translator resource, and writes the approved translations back into a resource file for each language, exactly where your build expects it.
It is the browser edition of our Windows tool, Translate Resx/Resw. Both read and write the same files, so a project can move between them.
What you need: a current web browser, a project folder with at least one
.resx or
.resw file, and an Azure AI Translator resource in your own Microsoft Azure subscription (free tier available; see
Create your Azure resource).
Getting started
- Open the app at www.freytag.us/app/translate-your-app/.
- Open your project folder. In Chrome or Edge, click Choose folder… and pick the folder of your application. The browser asks once for permission to read and write it. In Firefox or Safari, click Select folder…; the files are read into memory and you download the results at the end. You can also drag a folder onto the page, or click Open demo project to explore with a sample.
- Create the project. If the folder has no
apptranslator.atproj file yet, choose the source resource file (the one without a language suffix, for example Resources/Strings.resx), the source language code (usually en), the target languages, and click Create project and write work files. The app writes the settings file and one XLIFF work file per language into an xliff folder next to it.
- Sync whenever you change your source strings. Sync reads the resource file again, adds new strings, removes deleted ones, and marks strings whose text changed as "source changed" so they are translated again and reviewed.
The steps across the top of the app follow this order: Project, Translate Settings, Translate, Worksheet, Check & Export.
Create your Azure AI Translator resource
Azure AI Translator is Microsoft's machine-translation service. You create it once in your own Azure subscription; the app only uses it.
- Sign in to the Azure portal. If you have no Azure account, create one first; Microsoft offers a free account.
- Choose Create a resource, search for Translator, and click Create.
- Pick a subscription and a resource group (a folder for related Azure things), a region (for example East US), a name, and a pricing tier. F0 is free: up to two million characters a month, and it does not expire. S1 is pay as you go for larger volumes.
- After it is created, open the resource and choose Keys and Endpoint. Copy Key 1 and note the Region shown there. If the region is "global," leave the region box in the app empty.
Type the region in full. Azure wants the long name, such as southcentralus, not a short form such as scus. This matters more than it sounds: Azure refuses a short form with exactly the same message it uses for a wrong key, so you can spend an afternoon regenerating a key that was never the problem. The app now checks the region as you type and tells you the long name, but the value on Keys and Endpoint is always the one to copy.
Keep your key secret. Anyone who has it can translate on your account. Do not paste it into email or chat. If it leaks, open Keys and Endpoint in the portal and click Regenerate Key 1; the old key stops working at once.
The app translates at a pace that fits the free tier (about 33,000 characters a minute). If you chose S1 or higher, select that tier in Translate Settings and the app sends as fast as the service allows.
Translate Settings
| Setting | What it does |
|---|
| Key, Region, Endpoint | Your Translator credentials. The region must be the full name from Keys and Endpoint, such as southcentralus; leave it empty for a global resource. Leave the endpoint blank unless Microsoft gave your resource its own address. The app accepts an endpoint only at a Microsoft Translator address, so that your key cannot be sent anywhere else, including to us. Tick Remember these settings until this browser tab closes to keep them while you work; they are held in the tab's session storage and are gone when the tab closes. |
| Pricing tier | F0 paces requests to the free tier's limit; paid tiers are not paced. |
| Test connection | Translates the word "Hello" into French to prove the key, region and endpoint work. |
| Protect placeholders and markup | On by default. Each string is sent as HTML with {0}, %s and tags such as <b> marked "do not translate," so the service leaves them alone. Turn it off for strings that contain literal angle brackets the service misreads; the checks still catch any damage. |
| Reuse approved translations | Looks up the translation memory before calling Azure. Approved strings are added to the memory whenever you save the worksheet, whether or not this is on. |
| Line ends | Windows (CRLF) matches the Windows app. Choose Keep whatever each existing file uses for projects that use Unix line ends. |
| Quality checks | Each check can be an error (blocks export), a warning, an info note, or off. See Checks. |
| Glossary | Terms that must be translated a fixed way, per language, and product names that must not be translated at all. Terms are pinned in every Azure request and verified in every result. Saved to glossary.json. |
| Translation memory | Every approved translation, keyed by language pair and source text. Saved to translation-memory.json. Safe to keep in version control. |
Click Save project settings to write your choices into apptranslator.atproj. The key is never written to that file.
Translate
Estimate counts the strings and characters that will be sent, without contacting Azure. Translate now sends them, language by language, in batches of at most 25 strings and 10,000 characters. Strings found in the translation memory are filled from memory and not sent. Everything that comes back is marked Translated – Needs Review; nothing is exported until a person approves it. You can stop at any time; finished batches are kept.
The progress panel shows how many characters Azure has counted so far. Microsoft bills characters above the free tier.
Worksheet
The worksheet shows one work file at a time: every string's key, source text, translation, status, developer note, length limit, and any findings. Edit a translation directly. Set its status with the drop-down:
| Status | Meaning |
|---|
| Untranslated | No translation yet. |
| Translated – Needs Review | A machine, the memory, or an import produced it. A person has not checked it. |
| Reviewed | A person checked it. It is exported and added to the memory. |
| Final | Signed off for release. Also exported and remembered. |
Filters show only untranslated strings, strings needing review, strings whose source changed, or strings with findings. Mark all "needs review" as Reviewed approves a whole file after you have read it. Click Save to write the work file; unsaved edits are marked with a blue border.
A developer can add a length limit or a screenshot to a string inside its comment in the resource file: [maxlength:40] and [screenshot:shots/home.png]. The limit is checked; the note travels to the worksheet.
Checks
| Check | Default | What it finds |
|---|
| placeholders | error | A {0}, {name}, %s or %1$d missing from, or added to, the translation. A missing placeholder crashes the application at run time. |
| markup | error | A tag such as <b> missing or added. |
| untranslated | error | A string with no translation. |
| translated-needs-review | error | A string nobody has reviewed yet. |
| whitespace | warning | Leading or trailing spaces differ from the source. |
| length | warning | Longer than its [maxlength:N] limit, or more than three times the source length (a sign the service added text). |
| glossary | warning | A required term is missing, or a do-not-translate term was changed. |
Errors block export. Click a key in the findings table to jump to it in the worksheet.
Export and your files
Export writes Reviewed and Final strings into the translated resource file for each language: Strings.de.resx next to Strings.resx, or Strings/de/Resources.resw beside Strings/en-US/Resources.resw. Entries you did not change keep their exact bytes, so your version-control diffs show only real changes. A Testing build option also exports strings still needing review, for layout testing only.
The app reads and writes these files in your project folder:
| File | Purpose |
|---|
apptranslator.atproj | Project settings: files, languages, options. No secrets. |
xliff/Name.de.xliff | One work file per source file and language, with every string's status and history. |
glossary.json | Your terminology. |
translation-memory.json | Approved translations for reuse. |
Name.de.resx | The translated resource file your build uses. |
Name.qps-ploc.resx | The pseudo-localization test language, if you generated it. |
In Chrome and Edge the files are saved in place. In other browsers, Check & Export offers a zip of every changed file; unzip it over your project folder.
Browsers
| Browser | Read a folder | Save files in place | Download a zip |
|---|
| Chrome (current) | Yes | Yes | Yes |
| Microsoft Edge (current) | Yes | Yes | Yes |
| Firefox (current) | Yes | No | Yes |
| Safari (current) | Yes | No | Yes |
The app is tested with the current versions of these browsers on Windows and macOS. It does not run in Internet Explorer.
Privacy and your key
- Your resource files are read and written on your computer. They are not uploaded anywhere.
- The text of each string you translate is sent to your Azure AI Translator resource, and nowhere else. Microsoft's handling of that text is described in its data, privacy and security page for Azure AI Translator.
- Your key is held in the browser tab's memory (and, if you tick the box, in the tab's session storage). It is never sent to Freytag & Company and never written to your project files.
- After the page loads, the app makes no requests to www.freytag.us. The app page loads no advertising, analytics or translation widgets.
- Read the full privacy and security policy.
Sign in with Microsoft
When enabled, Sign in with Microsoft lets you use your work account instead of a key. The app obtains a short-lived token from Microsoft Entra ID and presents it to your Translator resource; no key is typed into the browser. To use it:
- In the Azure portal, open your Translator resource, choose Access control (IAM), and give your account the Cognitive Services User role. Role changes can take up to five minutes to apply.
- Copy the resource's Resource ID from its Properties page into the app.
- Fill in the Region box as well, using the full name from Keys and Endpoint, such as
southcentralus. Microsoft requires the region for every resource that is not global, whether you sign in or use a key. Leave it empty only for a global resource.
- Click Sign in with Microsoft and choose your work account.
If your organization requires an administrator to approve new applications, the app shows a link your Microsoft Entra administrator can open to grant consent for everyone in your organization. Sign-in is not available for personal Microsoft accounts.
If the sign-in button is not shown, this edition is running with keys only.
Working with the Windows app
The browser edition and Translate Resx/Resw for Windows use the same project file, work files, glossary and memory, and produce byte-identical files. Open the same folder in either. The Windows app adds features that need a desktop: a built-in local language model, Azure Key Vault sign-in, import of translations from other tools, a context builder, and a command-line tool for build servers.
Troubleshooting
- "Enter your Azure AI Translator key"
- Go to Translate Settings and enter the key, or sign in with Microsoft.
- "Azure Translator answered HTTP 401"
- Check the region before you touch the key. Azure sends this same message for a wrong key, for a region that does not match the resource, and for a regional resource used with no region at all. The commonest cause is a region written short, such as
scus instead of southcentralus. Copy Key 1 and the region from Keys and Endpoint in the Azure portal, and use the region exactly as shown. For a global resource leave the region empty. If the key and region are both right, check that the resource is a Translator resource: a multi-service Cognitive Services key works only against its own endpoint address.
- "The region is ... not ..." or "This app will not send your key to ..."
- These come from the app, not from Microsoft, and nothing has been sent. The first means the region was written short; use the long name the message gives. The second means the endpoint box holds an address that is not a Microsoft Translator one. Your key is only ever sent to addresses ending in
cognitive.microsofttranslator.com, api.cognitive.microsoft.com or cognitiveservices.azure.com. Leave the box blank for the usual endpoint. Azure Government and other sovereign clouds are not supported.
- "Azure Translator answered HTTP 403"
- The free tier's monthly quota is used up, or your subscription is disabled. Check the resource in the Azure portal.
- "HTTP 429" or slow progress
- The service asked the app to slow down. The app waits and retries by itself. Choose the correct pricing tier in Translate Settings.
- "Azure Translator request failed" the moment you click
- The browser blocked the call before it left. A company proxy, a browser extension, or a strict privacy setting can do this. Try another browser or network. If your Translator resource is locked to a virtual network, it cannot be reached from a browser; use the Windows app on a machine inside that network.
- "XLIFF work file not found"
- Go to Project and click Sync work files.
- "XML error at offset …"
- A resource or work file is not well-formed XML. Open it in an editor and fix the line near that position.
- The folder picker does not appear
- Your browser does not support in-place saving. Use Select folder… instead and download the zip when you finish.
- A language I need is not in the list
- The list is the set of languages both Azure AI Translator and the Microsoft Store accept. To add another code, edit
extraLanguages in apptranslator.atproj.
Still stuck? Email team@freytag.us or call (703) 579-5377.
Glossary of terms
- Resource file
- A
.resx or .resw XML file holding an application's strings.
- XLIFF
- XML Localization Interchange File Format, the standard exchange file for translations. The app's work files.
- Placeholder
- A marker such as
{0} or %s that the application replaces with a value at run time.
- Translation memory
- A store of approved translations, reused before any machine translation.
- Glossary
- Required terminology, per language, plus terms that must not be translated.
- Pseudo-localization
- A generated test language (
qps-ploc) with accented letters, brackets and extra length, used to find layout problems.
- Azure AI Translator
- Microsoft's machine-translation service, used through a resource in your own subscription.
- Microsoft Entra ID
- Microsoft's sign-in service for work accounts, formerly Azure Active Directory.
- Language code
- A short identifier such as
de or pt-br (the BCP-47 standard).