Developer Hint: String codes instead of actual strings

TLDR; Use string codes instead of actual strings even if you have only one language supported. For example, {{ "alex_panshin.hello_page.title"|trans }} is much better than {{ "Hello, world!" }} just because you are ready for i18n at every moment, it’s easier to change and find and this change is much less error-prone.


Okay, let’s consider usual lifecycle of a template string. For example, this one:

<h2>Hello, world!</h2>

Meh, what’s the problem? Actually, everything is absolutely ok until your project manager comes to you and says:

“Hi, John Doe! We gonna translate our hello-world website into French. Can you please do this?”

Yes, kinda obvious, you can. You’ve jest finished yet another book telling you that keeping things simple is the best solution in all cases. You decide that the most simple way to achieve the goal is just extract all the strings into a file and add translations:

<h2>{{ 'Hello, world!'|trans() }}</h2>
"Hello, world!": Bonjour le monde!

So far so good. You do not need to create translations file for English, because you used English phrases as string keys. Awesome? Yeah, until your manager returns and says that now he needs to add Spanish and German languages. Ya, piece of cake. Just add two translation files.

And, finally, project manager comes to you and says that he wants to change the English phrase to “Hello, brave new world!” and do not change other translations.

Ouch! Here is the turning point of the story. You can choose from two bad-n-fast solutions and good one:

  1. Just replace the string in template and change all translation files. This is bad just because your change of string in one translation causes you change several files for other languages.
  2. Ok, create English translation file with only one string. Or grab all of them. This will be kinda strange, since you have exactly the same string in template and some maintainer can be confused with this. Especially in case you decide to create translation file only one string.
  3. Replace all strings in templates with string codes. And finally create English translation file. This is the most complex way of doing the job. But this will solve the translation problem forever.

The problem is you have no time for third way :(


My solution is quite simple. Always use translation string codes even the website is only on one language. This seems a bit harder at first, but you will gain more benefit during site maintenance. So, if you are not yet persuaded, here it is the list of pros of this approach.

It looks unnatural on the page

Easier to find non-translated strings in any language developer uses as a fallback.

It’s easier to change

If you use natural English phrases to identify translation string, it’s a whole quest to change this text in english.

No duplication problems

Sometimes this phrase should be translated from English to %languageName% to different strings. That is impossible to achieve if you use natural phrases as translation keys, since they are equal.

You always have the full list of translation keys

If you need to add the second language, you just copy the file, delete all translation values and you’re ready to translate. No need to gather all the strings from entire code base.

Possible drawbacks

The most popular counter arguments of this approach are listed below:

But my %frameworkName% (or %companyName%) uses natural phrases!

Just do not give a shit, break this tradition and use translation codes. Share the knowledge with your teammates and persuade them. This worth the cost, really!


Yes, this approach generates a bit of overhead for single-language websites. If you work in high-load project you should task this into account.

Alex Panshin avatar
About Alex Panshin
Software Engineer from Russia. Interested in PHP, Scala, microservices and Big/Fast Data stuff.
comments powered by HyperComments