Technical Translation: Docs, UI & Error Messages

Translating a marketing brochure and translating a software manual are completely different jobs. Marketing text gives you creative freedom. Technical text does not. One wrong word in an error message can send a developer down a two-hour debugging rabbit hole. A mistranslated UI label can make a button do the opposite of what users expect.

Technical translation covers documentation, user interfaces, API references, error messages, code comments, and configuration files. Each type has its own constraints. This guide covers what those constraints are and how to handle them without breaking things.

What makes technical translation hard

General translation focuses on meaning. Technical translation focuses on meaning and precision. You're working with content that has strict rules about what can and cannot change.

Here's what you're up against:

Placeholders and variables: Strings like Welcome, {username}! or %d items remaining contain code that must survive translation untouched. Translate the word inside the braces and your app crashes.
Consistent terminology: If you call it "dashboard" in the navigation, it needs to be "dashboard" everywhere. Not "control panel" on one screen and "overview" on another. Users get confused fast.
Character limits: A button that says "Submit" (6 characters) might need to say "Absenden" (8 characters) in German or "Soumettre" (9 characters) in French. UI elements have hard width constraints.
Code blocks: Documentation often includes code samples. These must pass through translation completely unchanged.
Platform conventions: iOS says "Settings." Android says "Settings" too, but the German iOS says "Einstellungen" while the German Android might use a different term. Platform-specific terminology matters.

Translating UI strings

UI strings are the shortest and most constrained type of technical content. Every word matters because space is limited and users make decisions based on what they read.

Handle placeholders correctly

Most UI strings contain dynamic values. These look different depending on the framework:

React/i18next: You have {{count}} new messages
Android: %1$s shared a photo with you
iOS: %@ invited you to join
Python/gettext: %(user)s has %(count)d items

The rule is simple: translate the text around the placeholders, never the placeholders themselves. But word order changes between languages. In English you might write {user} uploaded {count} files. In Japanese, the word order flips: {user}が{count}個のファイルをアップロードしました. The placeholders need to move with the grammar.

A good translation API handles this automatically. It recognizes placeholder patterns and preserves them during translation while allowing word reordering. If you're using a tool that mangles your placeholders, that's a problem you'll discover in production when users see raw template strings.

Watch string length

German text is typically 30% longer than English. Finnish can be 40% longer. Chinese and Japanese are often shorter. This isn't trivia. It breaks layouts.

Practical approaches:

Design UI with 40% extra space for text expansion
Use abbreviations where the target language has accepted short forms
Test translated strings in the actual UI, not just in a spreadsheet
Set maximum character limits per string in your localization files

Maintain a terminology glossary

Before translating any UI, build a glossary of key terms with approved translations. This prevents the "dashboard vs. control panel" problem. Your glossary should cover:

Navigation items (Home, Settings, Profile, Help)
Action verbs (Save, Delete, Submit, Cancel, Confirm)
Status labels (Active, Pending, Failed, Processing)
Product-specific terms (workspace, project, team, channel)

This glossary becomes your source of truth. Every translator working on your project should use it. If you're using a translation management system, upload the glossary there so it's enforced automatically.

Translating documentation

Documentation is longer and more complex than UI strings. You're dealing with paragraphs, code samples, tables, and cross-references. The challenge is translating the explanatory text while leaving technical elements untouched.

Protect code blocks

API documentation and developer guides contain code samples that should never be translated. Not the variable names, not the comments (debatable), not the function calls. Here's what typically goes wrong:

A machine translation engine translates response.status to antwort.status
Code comments get translated inconsistently
File paths like /usr/local/bin get mangled
Command-line examples get partially translated

The solution depends on your documentation format. If you're using Markdown, code blocks between triple backticks should be excluded from translation entirely. If you're using HTML, wrap code in <code> tags. Most translation APIs and TMS platforms recognize these markers. Langbly's API preserves HTML tags and their contents, so code wrapped in <code> or <pre> tags passes through untouched.

Handle cross-references

Documentation links to other documentation. When you translate a page title from "Getting Started" to "Erste Schritte," make sure the link text updates too. Broken cross-references are one of the most common issues in translated docs.

If your docs use slug-based URLs (like /docs/getting-started), keep the slugs in English. Only translate the visible link text. This avoids the nightmare of maintaining parallel URL structures across languages.

Decide on code comment translation

This is genuinely debatable. Arguments for translating code comments: developers who aren't fluent in English understand the code better. Arguments against: mixed-language code is harder to search, and most programming terms don't have good translations.

My recommendation: translate comments in beginner-facing tutorials. Leave them in English for API references and advanced documentation. If your audience is primarily non-English-speaking developers (common in Japan, Korea, and parts of Latin America), translate comments.

Translating error messages

Error messages are the highest-stakes technical content. When something breaks, users need to understand what happened and what to do. A confusing translated error message turns a recoverable problem into a support ticket.

Keep error codes visible

Never translate error codes. ERR_CONNECTION_REFUSED should stay exactly that in every language. The error code is what users search for and what support teams use to diagnose issues. Translate the human-readable description that accompanies it.

Good pattern: [ERR_AUTH_FAILED] Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihre Anmeldedaten.

Bad pattern: Translating the error code itself, or dropping it entirely.

Preserve technical details

Error messages often contain file paths, URLs, port numbers, and stack traces. These are debugging information. Translate the message structure, but leave technical values alone:

Good: Datei nicht gefunden: /var/log/app.log
Bad: Datei nicht gefunden: /var/protokoll/app.log

Test error states in every language

Most QA processes focus on the happy path. You log in, things work, translations look fine. But errors are where translated UI falls apart. Run through these scenarios in every target language:

Form validation errors (too short, too long, invalid format)
Network errors (offline, timeout, server error)
Authentication failures (wrong password, expired session, rate limited)
Permission errors (not authorized, read-only)

File format considerations

The format of your source files affects how translation works. Here's what to know about the common ones:

JSON (i18next, react-intl)

The most common format for web apps. Keys are developer-facing identifiers; values are the translatable strings. Nested structures let you organize by feature or screen.

Watch out for: ICU message format strings with pluralization rules ({count, plural, one {# item} other {# items}}). These need careful handling because plural rules differ between languages. Arabic has six plural forms. Japanese has one.

XML (Android resources, XLIFF)

Android's strings.xml is straightforward but has quirks. String arrays and plurals need special attention. XLIFF is the industry-standard exchange format that most TMS platforms support.

PO files (gettext)

Common in PHP (WordPress), Python (Django), and Ruby projects. The format handles pluralization well and has built-in support for translator comments and context. If you're translating a WordPress plugin or theme, you're working with PO files.

YAML (Rails, Hugo, Jekyll)

YAML is clean and readable but whitespace-sensitive. A translation that changes indentation breaks parsing. Make sure your translation workflow preserves YAML structure exactly.

Machine translation for technical content

Machine translation has gotten remarkably good at technical content. Context-aware translation engines handle placeholders, code blocks, and consistent terminology better than traditional statistical approaches. But you still need human review for anything user-facing.

A practical workflow for technical documentation:

Extract translatable strings (exclude code blocks and technical identifiers)
Run through a translation API that respects formatting and placeholders
Have a technical reviewer check terminology consistency
Test in the actual application or documentation site
Build corrections back into your quality management process

For UI strings, the workflow is tighter because every string is visible to users. Machine translate, then have a native speaker who knows your product review every string in context. "In context" matters. A string that reads fine in a spreadsheet might look wrong when it's actually on the button.

The cost equation works strongly in favor of machine translation for technical content. Translating 50,000 strings across 10 languages with professional translators can cost $50,000-$100,000. Using a translation API for the first pass and having translators review and correct brings that down to $5,000-$15,000, depending on how much correction is needed.

Continuous localization for technical products

Software ships continuously. Your translations need to keep up. The old model of translating everything in a big batch before a quarterly release doesn't work for teams shipping weekly or daily.

Continuous localization means:

New strings are detected automatically when code is merged
Machine translation generates a first draft within minutes
Translators review in parallel with development
Translated strings ship with (or shortly after) the feature

This requires tooling. A TMS with Git integration (Crowdin and Lokalise are the strongest here) detects new strings from your repo. A translation API provides instant first-pass translations. Human reviewers clean up anything the API got wrong.

For the software localization workflow to work at speed, your translation API needs to handle your specific file formats and placeholder conventions without breaking them. Langbly's API is Google Translate v2 compatible, which means existing integrations with TMS platforms and CI/CD pipelines work without modification.

Common mistakes

After working with dozens of technical translation projects, these are the mistakes I see most often:

Concatenating strings: Building sentences from fragments like "You have " + count + " items" instead of using proper placeholder strings. This breaks in languages with different word order.
Hardcoding text: Burying translatable strings in code instead of extracting them to resource files. You'll miss them during translation.
Ignoring context: The word "Post" means different things as a noun (a blog post) and a verb (to post something). Without context, translators guess wrong.
Skipping pseudo-localization: Before translating, run pseudo-localization (replacing characters with accented versions and adding length) to find UI issues early.
Translating what shouldn't be translated: Brand names, product names, technical identifiers, and code should stay in English unless you have a specific localized version.

Getting started

If you're beginning to translate technical content, start small. Pick one language and one content type (UI strings are the most impactful). Build the workflow, fix the issues, then expand to more languages and content types.

Read the localization strategy guide for the broader framework. For hands-on API integration, the Langbly documentation covers how to translate strings programmatically while preserving formatting and placeholders.

Technical Translation: How to Translate Documentation, UI Strings, and Error Messages