Software Localization Best Practices: Complete Developer Guide

Prevent translation bugs in your software localization process. Learn code structure, placeholder syntax, and UI patterns. Includes free AI translation tool.

When you don’t prepare for software localization, your French users may end up seeing this:

The reason? Because your code looks something like this:

<button style="width: 120px">Save Changes</button>

<button style="width: 120px">Save Changes</button>

This guide shows you how to structure your code for localization from day one. Each section includes clear examples and highlights what makes the biggest difference to translation quality.

What you’ll learn:

• How to use separate files for localizable content
• Best practices for handling placeholders and dynamic content
• UI design patterns for text expansion
• How to load the right language for your users
• How to set up automated translations

Tip #1: Use Separate Files for Localizable Content

Translation tools can’t detect hard-coded strings in your source code. Move all user-facing text into resource files. This includes:

• UI labels, buttons, and menu items
• Error messages and validation text
• Email templates and notifications
• Help text, tooltips, and placeholder text
• Success/confirmation messages

Use your framework’s internationalization functions instead of hard-coding strings.

React example:

// Wrong - hard-coded
<button>Submit</button>

// Right - using react-intl
<button>{t('submit_button')}</button>

// Wrong - hard-coded
<button>Submit</button>

// Right - using react-intl
<button>{t('submit_button')}</button>

WordPress example:

// Wrong - hard-coded
echo 'Submit';

// Right - using WordPress i18n
echo __( 'Submit', 'your-textdomain' );

// Wrong - hard-coded
echo 'Submit';

// Right - using WordPress i18n
echo __( 'Submit', 'your-textdomain' );

Rails example:

# Wrong - hard-coded
flash[:notice] = "Profile updated successfully"

# Right - using Rails I18n
flash[:notice] = t('profile.update_success')

# Wrong - hard-coded
flash[:notice] = "Profile updated successfully"

# Right - using Rails I18n
flash[:notice] = t('profile.update_success')

Select the resource file format based on your framework:

• .json – JavaScript frameworks (React, Vue, Angular)
• .po/.pot – WordPress, PHP, Python (gettext)
• .yaml/.yml – Ruby on Rails
• .xml – Android (strings.xml)
• .xcstrings – iOS/macOS

Tip #2: Handle Placeholders and Dynamic Content Properly

When text includes dynamic values like usernames, counts, or dates, use placeholders instead of string concatenation.

Different languages have different word orders. Concatenation breaks this by splitting sentences into fragments that can’t be reordered.

The example below creates three separate pieces that translators can’t rearrange. In languages like Japanese where word order differs from English, the translation becomes grammatically incorrect.

Incorrect Example (String Concatenation)

const name = 'John';
const message = 'Hello, ' + name + '!';

const name = 'John';
const message = 'Hello, ' + name + '!';

Correct Examples

msgid "Hello, %s!"
msgstr ""

msgid "Hello, %s!"
msgstr ""

{
  "greeting": "Hello, {name}!"
}

{
  "greeting": "Hello, {name}!"
}

greeting: "Hello, %{name}!"

greeting: "Hello, %{name}!"

Make sure to use placeholder syntax that works with your framework:

Tip #3: Design the UI for Text Expansion

Text length changes dramatically across languages. Fixed-width layouts, buttons, and navigation menus break when text expands or when you support right-to-left languages like Arabic.

• German text is typically 30% longer than English
• French runs about 20% longer
• Asian languages like Chinese and Japanese are often shorter

Before you start coding, think through how different languages impact space during the design phase. This saves time debugging layout issues later.

For implementation details and code examples, see how to prevent layout issues with long translations.

Tip #4: Write Content That Translates Well

Clear, simple writing produces better translations. Complex language requires more editing after translation.

✓ Write full sentences with clear subjects and actions.

Correct Example

"You have no saved items in your cart."

"You have no saved items in your cart."

This clearly states what’s empty (cart) and what it should contain (saved items).

Incorrect Example

"No cart items."

"No cart items."

The example above is missing the subject (“you”) and action (“have”). These fragments could mean “There is no cart” or “Items not in cart” depending on how they’re interpreted.

✓ Keep it simple. Short, clear words produce better translations than complex vocabulary.

Correct Example

"Remove item from cart"

"Remove item from cart"

Incorrect Example

"Eliminate this article from your shopping cart"

"Eliminate this article from your shopping cart"

✓ Avoid idioms and cultural references.

Phrases like “piece of cake” or “hit a home run” don’t translate literally and may not make sense in other cultures.

Tip #5: Configure Language Detection and File Loading

Set up your application to detect the user’s language and load the appropriate translation file. Most modern frameworks include i18n libraries that handle this automatically.

• React with react-i18next

React doesn’t include i18n by default. Install react-i18next with npm, then configure it to detect the browser language and load your translation files.

• Ruby on Rails

Rails includes I18n by default. Configure it in config/application.rb. Then, detect the user’s language in your ApplicationController.

• WordPress

WordPress handles language detection automatically. Users set their site language in Settings → General, and WordPress loads the corresponding .mo file from wp-content/languages/. For multilingual sites where different users need different languages, you’ll need a plugin like WPML to handle per-user language selection.

Handle Missing Translations

Set your fallback language to your primary language. When a translation file doesn’t exist or strings are missing, users see the fallback instead of broken text or translation keys.

Add a Language Switcher (If Needed)

Most applications should respect the user’s browser or device language settings automatically. But if you want to let users manually override this—common for web applications—add a language switcher and store their choice:

// Save user's manual language selection
localStorage.setItem('userLanguage', selectedLanguage);

// Check for manual selection first, then use browser default
const userLanguage = localStorage.getItem('userLanguage') || navigator.language;

// Save user's manual language selection
localStorage.setItem('userLanguage', selectedLanguage);

// Check for manual selection first, then use browser default
const userLanguage = localStorage.getItem('userLanguage') || navigator.language;

Mobile apps typically don’t include language switchers since users expect apps to follow their device settings.

Tip #6: Automate Your Software Translation Process

Manual translation workflows slow down every release. When you update strings, translations need to happen automatically.

PTC is an AI translation tool that automates this process. You can integrate it with your GitHub, GitLab, or Bitbucket repository, or use the API for CI/CD integration. When you update strings, translations happen automatically.

Creating an account is free, and you can translate 2,500 words into 2 languages at no cost. After that, there’s no subscription fee—you only pay for what you translate.

Tip #7: Test Localized Versions Before Launch

Testing ensures your translations display correctly and your UI works across different languages. Test both display and functionality.

• Layout: Text fits without truncation, no overflow, navigation works
• Functionality: Forms submit, error messages display correctly, search handles special characters (é, ñ, ü)
• Formatting: Dates (DD/MM vs. MM/DD), numbers (1,000.00 vs. 1.000,00), currency positions (€100 vs 100€)