How to Translate YAML Files with PTC

PTC gives you Better Than Human AI translations for YAML files used in frameworks like Ruby on Rails, Laravel, and Symfony. Follow these steps to prepare and translate your .yml files using PTC.

Translating YAML Files with PTC: First-Time Setup

To get accurate, easy-to-maintain translations, you’ll need to:

  • Add all translatable text to YAML files and use placeholders properly
  • Connect your repository to PTC
  • Provide PTC with basic project context
  • Merge the translations

Once set up, PTC continuously monitors your repository. It detects new or modified text in .yml files and translates it automatically.

Step 1: Add All Translatable Text to YAML Files

Your software should store every translatable string in a .yml file using key-value pairs. PTC looks for these files in your repository and extracts the string values for translation.

Correct – All text in a .yml file

en:
  homepage:
    title: "Welcome to our website"
    description: "Discover our products and services"
  form:
    submit: "Submit"
    reset: "Reset"

Incorrect – Hardcoded text in code

<%= "Welcome to our website" %>

If you hardcode user interface (UI) text in templates or scripts, PTC can’t access or translate it. 

Step 2: Use Placeholders for Dynamic Content

Use placeholders for any part of a string that is dynamic, like a name, number, or date. Don’t break the sentence into multiple strings or concatenate values at runtime.

PTC supports all common placeholder formats, such as %{name}, {name}, and {{name}}.

Correct Full string with placeholders

en:
  greeting: "Hello, %{user_name}! Today is %{current_date}."

Incorrect – Split strings

en:
  greeting_start: "Hello, "
  greeting_end: "! Today is "

Splitting strings can break sentence structure in other languages, which leads to incorrect translations.

Step 3: Create a PTC Account and Connect Your Repository

PTC connects directly to your GitHub, GitLab, or Bitbucket repository. You grant access so it can read and write files.

Here’s how it works:

  1. Sign up for a free 30-day trial to get full access to all PTC features 
  2. Connect your repository to PTC
  3. PTC scans your repository for .yml files
  4. PTC shows you the files it will translate and suggests where to write the translated versions. You can accept the default output paths or change them to match your project’s folder structure.

Step 4: Provide Project Details and Select Target Languages

PTC uses context to deliver accurate translations. To make this possible, you’ll need to:

  • Provide the name of your software
  • Describe what it does and who it’s for
  • Select the languages you want to translate into

This helps PTC adjust phrasing, tone, and terminology to match your product.

Step 5: Confirm Translated Files Were Sent to the Right Location

After PTC completes the translation, it creates a merge request in your repository with the translated .yml files.

Your don’t need to review the translations. You need to confirm that:

  • All expected translation files were created
  • Translations appear written to the correct folder
  • The structure matches what your software expects

If a file is missing or saved in the wrong location, go to your project dashboard in PTC. Under Settings, adjust the output paths as needed.

Step 6: Check the Translation Quality Score in PTC

Before you deploy the translations, check your PTC dashboard for the translation quality score. PTC may ask for clarification in cases like:

  • A word might be a proper name, but PTC isn’t sure
  • A translation exceeds the maximum length allowed for a target language
  • A string could be interpreted in more than one way
PTC suggests how you can improve your translation quality score

Responding to questions and suggestions from PTC lets you:

  • Improve translation quality
  • Avoid layout problems caused by long or incorrect translations
  • Teach PTC how to handle similar cases in future updates

Step 7: Test That Your Software Loads the Right Files

Once you’ve merged the translation files, test your product in a development or staging environment to make sure everything works as expected.

Check that:

  • Your software loads the correct .yml file for the selected language
  • Your language switcher or detection logic works
  • You don’t see untranslated strings (if you do, these may be missing from the source file)
  • Placeholders are correctly replaced with runtime values

Testing in a real environment is the best way to catch setup errors and confirm that translations are being applied throughout the software.

Bonus: Translate Content That’s Not Stored in YAML Files

Some parts of your product may include user-facing content that isn’t stored in .yml files or tracked in version control. This often includes things like:

  • Onboarding emails
  • System-generated emails (like password reset or subscription confirmations)
  • Release notes

You can translate this type of content using the Paste to translate feature in PTC:

  1. From the PTC dashboard, go to Translations → Paste to translate
  2. Paste your text and pick the target languages
  3. Copy the translated text and insert it where it belongs

PTC Keeps Your YAML Translations Up to Date

After the initial setup, PTC keeps your translations in sync. When you change or add strings in a .yml file, PTC detects the updates in your connected branch and translates the new or modified strings. It then sends a new merge request with the updates.

You don’t need to go through the setup again or re-upload files. Translations stay aligned with your code as your product evolves.

Start Translating YAML Files with PTC

Create your free 30-day trial. Translate your .yml files automatically, receive translations as merge requests, and keep everything up to date as you develop.

Scroll to Top