Validating Translation Files in Multilingual Projects

TYPO3 Questions Multilanguage
1

TL;DR
I built a Composer plugin to automatically validate translation files in multilingual TYPO3 (and other PHP projects). It catches common issues like missing keys, broken placeholders or invalid syntax. I’d love to hear how others handle translation quality in their workflows.

In multilingual TYPO3 projects (or really any PHP-based application), it’s not uncommon in my experience to run into issues with translation files — missing keys, inconsistent placeholders, or invalid syntax. Unfortunately I’ve run into these problems myself more than once. Even with good development workflows, some issues only surface late.

To improve this situation for myself, I built a small Composer plugin to validate all translation files within a project:

move-elevator/composer-translation-validator

How it works

Once installed, the plugin offers a command:

composer validate-translations ./Resources/Private/Language

It will scan all translation files (JSON, YAML, PHP, XLIFF) in your project and validate them using a set of rules. Some of the things it currently checks for:

  • Duplicate translation keys
  • Missing or empty values
  • Mismatched or broken placeholders (like %username%)
  • Invalid syntax
  • Key conflicts across multiple files
  • Inconsistent use of placeholder syntax or key formats
  • and more …

It supports typical TYPO3 translation formats (e.g. XLIFF) as well as other frameworks like Symfony or Laravel (with JSON, YAML or PHP translation formats).

Why I built it

In my own projects, especially the larger multilingual ones, I noticed how easy it is to overlook translation issues. A missing key here, an unused string there, or the classic typo in a placeholder that breaks a view.

While external tools like Crowdin or Lokalise are great for managing translations in larger teams, I wanted something lightweight and developer-focused. Something I can run locally, commit-safe, and integrate into my CI pipelines.

What I’m asking the community

I’d be curious to hear:

  • Are you facing similar problems with multilingual setups in TYPO3?
  • Do you rely on any other tools or workflows to catch translation-related issues early?
  • Would something like this be useful in your projects?
  • Are there additional checks you’d find helpful?

I’m happy to take suggestions or feedback or even better: if you’ve got a validator idea, feel free to open a GitHub issue or PR.

Thanks so far!

Cheers,
Konrad

2 Likes
2

Hi @kmi!

Nice project! Thank you for posting about it here on talk.typo3.org. :grinning:

Have you blogged about this anywhere? If not, I’m thinking this could be a nice article on typo3.org. Do you have any TYPO3-specific examples of your plugin in use with a TYPO3 extension?

1 Like
3

Hej @mabolek,

Thanks for the quick response.

The Composer plugin is still relatively new, so I don’t have any detailed articles about it yet, apart from the documentation in the GitHub repository.

I currently use the language validation in some of my TYPO3 extensions in the linting processes, for example in EXT:xima-typo3-content-planner.

A good example that I have repeatedly encountered in my own projects is the use case where you create a new translation entry but forget to do so in another language.

> composer validate-translations ./Resources/Private/Language

Resources/Private/Language/de.locallang.xlf

  MismatchValidator
    - Warning  the translation key `key2` is missing but present in other translation files (`locallang.xlf`)

+-----------------+------------------+----------------+
| Translation Key | de.locallang.xlf | locallang.xlf  |
+-----------------+------------------+----------------+
| key2            |                  | English Key #2 |
+-----------------+------------------+----------------+

...

 [WARNING] Language validation completed with warnings.
1 Like
4

Hey this is pretty nice. I do something similar (but with only 75% of your feature set) in a commercial project.

I wonder though if structurally it would make sense to offer this as a Symfony CLI command (distributed to vendor/bin/language-validate) or so. Then you might even be able to wrap it into a TYPO3 CLI command, too (without too much code redundancy, if it uses the same framework). I think that could feel more “natural” to TYPO3 users, where composer plugins usually are more behind the scenes, and actual actions are exposed as commands outside the “composer …” scope.

Theoretically I guess the code could be made so it supports all three variants (composer plugin, Symfony CLI standalone command, TYPO3-enabled CLI command).

Either way: Thanks a lot for sharing this, I like it!

1 Like
5

Hej @ghi,

That sounds like an interesting idea. Expanding into other commands also seems like a good step toward integration into various frameworks.

In fact, I initially took the opportunity to write my own Composer plugin. :smiley:

Thanks for the idea, I’ll think it through in detail.

Cheers,
Konrad

6

It would be extremely helpful to be able to find orphaned keys in TYPO3 extensions.
I know the key is often compiled programmatically, but a check like this would provide useful information about where to look.
I’ve created a feature request for that on GitHub.