Developer Guides

How to Prepare Your Software for Translation

Before you start using PTC, make sure your software handles text correctly, uses placeholders, and loads the right language for each user.

Preparing Your Software for Translation for the First Time

To get your software ready for translation, you’ll need to:

  • Move all user-facing text into resource files
  • Use placeholders for dynamic content
  • Load the correct translation file based on the user’s language

These steps apply across programming languages and frameworks. PTC supports multiple resource file formats—including .po, .json, .yaml, .strings, and .xml. 

1. Move All User-Facing Text into Resource Files

Put all user-facing text like labels, error messages, and user prompts into resource files. PTC reads from resource files, and it does not detect hard-coded strings in your source code.

Most frameworks include an internationalization (i18n) function or library that helps you mark translatable text and store it in the right resource file format.

  • In React and Vue, libraries like react-intl and vue-i18n provide you with a way to load and use translation files. The translations are then stored in the JSON files you generate.
  • Ruby on Rails includes the I18n module.
  • WordPress uses the __() function to mark strings for translation, which then get compiled into PO files.

 Correct Example (React and JSON File)

In your code:

<button>{t('submit_button')}</button>

In your resource file (en.json):

{
  "submit_button": "Submit"
}

 Correct Example (WordPress and PO File)

In your code:

<?php echo __( 'Submit', 'your-textdomain' ); ?>

In your resource file (en.json):

msgid "Submit"
msgstr ""

Incorrect Example (Hard-coded string)

<button>Submit</button>

2. Use Placeholders for Dynamic Content

When your text includes dynamic values, such user names, dates, or numbers, don’t insert them directly into the string. Use placeholders instead. This keeps translations accurate and avoids breaking the grammar or layout in other languages.

PTC detects and preserves placeholders during translation.

 Correct Examples

PO File:

msgid "Hello, %s!"
msgstr ""

JSON File:

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

YAML File:

greeting: "Hello, %{name}!"

Incorrect Example (String Concatenation)

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

If you split or build strings in your code, PTC won’t see the full sentence. That can lead to incorrect grammar, awkward phrasing, or missing translations.

Make sure to use placeholder syntax that works with your framework. Here are some common patterns:

File FormatCommon Placeholder SyntaxUsed In
.json{name}JavaScript (React, Vue)
.yaml%{name}Ruby on Rails
.po%s, %d, %1$s, %2$dWordPress, PHP
.xml%1$s, %2$dAndroid
.strings%@, %d, %fiOS/macOS

3. Make Sure Your Software Knows How to Load Resource Files

Once your text is stored in resource files, your app needs to load the right file based on the user’s language. Without this step, the user won’t see the translations.

Most frameworks and platforms support this through their i18n tools:

  • React/Vue: Use libraries like react-intl or vue-i18n, which handle loading the correct files at runtime
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  locale: detectBrowserLanguage(),
  messages: {
    en: require('./locales/en.json'),
    fr: require('./locales/fr.json')
  }
})
  • Ruby on Rails: The I18n module loads YAML translation files automatically
I18n.locale = request.env['HTTP_ACCEPT_LANGUAGE']
  • WordPress: Loads .mo files automatically based on the site language

In web apps, you can also detect the user’s preferred language from the browser and use it to set the default. For example:

  • React/Vue

Use the i18next-browser-languagedetector library to automatically detect the browser language. This library checks the browser’s language settings and applies the appropriate language as the default.

  • Ruby on Rails

Detect the browser language using the HTTP_ACCEPT_LANGUAGE header and set the language with I18n.locale.

For mobile apps, platforms like Android and iOS load resource files differently:

  • Android: Stores translation files in the res/values directory, with subfolders for each language (e.g., res/values-fr for French). Android loads the correct language file based on the device’s system settings.
  • iOS:  Place .strings files in language-specific .lproj folders (e.g., en.lproj/Localizable.strings). iOS selects the appropriate folder automatically.

4. Add a Language Switcher (If Needed)

As covered in the previous step, most platforms use system or browser settings to load the default language. But some users may want to switch to a different one, especially on the web. A language switcher gives them that option.

It’s optional, but often improves accessibility and user control. Implementation differs depending on the framework:

React/Vue

Use libraries like react-intl or vue-i18n to set the language. You’ll need to create the language switcher yourself (e.g., a dropdown or button) to reload the appropriate resource files based on the user’s selection.

Ruby on Rails

The I18n library lets you programmatically change the language, but you must design the language switcher interface. The app reloads the page with the correct YAML file once the user selects a language.

WordPress

Themes and plugins use the language set in the backend. To translate user-generated content or provide a front-end language switcher, use a multilingual plugin like WPML.

Translating Your Resource Files with PTC

Once your files are ready, you can translate them with PTC. You don’t need to copy-paste strings or hire human translators. PTC delivers Better Than Human Translations, optimized for your product’s tone, audience, and platform.

Step 1: Sign Up and Choose How to Use PTC

Start your free 30 day trial of PTC. You can choose from three ways to use PTC: connecting your Git repository, uploading files manually, or using the API to send and receive files programatically.

Step 2: Set Up Your Project

Next, you’ll set up your project.

You’ll be asked for your product name, what it does, who it’s for (target audience), and languages you want to translate into.
This information helps PTC understand your project’s context and generate accurate translations that read like they were written by an industry expert.

Step 3: Receive AI-Powered Translations via Merge Request 

How PTC delivers Better Than Human Translations depends on how you chose to work with it:

Git integration – PTC sends a merge request with translated files. Review and merge when ready.
Manual upload – Download the ZIP file with the translation files and add them to your project manually.
API – Use the API to fetch translated files.

Step 4: Keep Translations Up to Date

As your product evolves, you’ll update or add new strings. PTC helps keep your translations in sync. How it works depends on how you use it:
With Git integration: PTC watches your connected branch. When it detects changes in your resource files, it translates the new or updated strings and sends a new merge request.
With manual upload: Re-upload the updated files through the PTC dashboard. PTC will translate the new strings and let you download the updated files.
With the API: Push updated files to PTC via the API. Then, fetch the translations when they’re ready.

Ready to Translate Your Software?

You’ve prepared your resource files—PTC takes it from here. Start your free trial to get context-aware, Better Than Human Translations for your software.

Try PTC for free

Start typing and press enter to search

Scroll to Top