Style Guide
- key pattern:
<page>[.section].<component>[.attribute]
-
camelCase
for multiple words
Background
What are possible ways to map strings in JSON?
You would probably start with plain object:
{
"Login": "Login",
"Logout": "Logout",
"New post": "New post",
}
And you will create same file for each language, just changing values with translations.
But what if you decide later to change New post
to Add post
? You will need to change the key in all language files and in all source code files.
Alternative way is to use more abstract keys, that gives you more flexibility. For example:
{
"login": "Login",
"logout": "Logout",
"new": "New post",
}
And what if you now have another feature: Add event
? You alternatives are:
1) make complex keys
2) group by meaning
Complex-word keys would be:
{
"login": "Login",
"logout": "Logout",
"newPost": "New post",
"newEvent": "New event",
}
And what if now you have a login screen, which has a title, subtitle, 2 fields and submit button?
You might do this:
{
"loginTitle": "Login",
"loginSubtitle": "Please login to continue",
"loginSubmit": "Continue",
"logout": "Logout",
"newPost": "New post",
"newEvent": "New event",
}
And what if you have a registration screen which have similar elements?
{
"loginTitle": "Login",
"loginSubtitle": "Please login to continue",
"loginSubmit": "Continue",
"registerTitle": "Registration",
"registerSubtitle": "Create new account",
"registerSubmit": "Start",
"logout": "Logout",
"newPost": "New post",
"newEvent": "New event",
}
As you see translation file grows exponentially. You can make life easier for developers and translators by grouping keys:
{
"login": {
"title": "Login",
"subtitle": "Please login to continue",
"submit": "Continue",
},
"register": {
"title": "Registration",
"subtitle": "Create new account",
"submit": "Start",
},
"logout": "Logout",
"post": {
"new": "New post"
},
"event": {
"new": "New event"
}
}
When grouping elements look for similarities, what those elements have in common and how it would scale.
Input element can have label, placeholder, error. Those are attributes of that element, so it make sense to group values by element name, i.e. in our login screen:
{
"login": {
"title": "Login",
"subtitle": "Please login to continue",
"submit": "Continue",
"username": {
"label": "Enter your username",
"placeholder": "JohnDoe",
"error": "Username is a required field",
}
},
}
But what if there are more error messages later? If we need to add error message for complexity validation (i.e. "Please use numbers, letters, special symbols"). Both are errors, so we would group them under errors.
How does this look in YML?
YML looks similar to JSON, just without curly brackets:
login:
title: Login
subtitle: Please login to continue
submit: Continue
username:
label: Enter your username
placeholder: JohnDoe
error: Username is a required field
or you can also do it per line:
login.title: Login
login.subtitle: Please login to continue
login.submit: Continue
login.username.label: Enter your username
login.username.placeholder: JohnDoe
login.username.error: Username is a required field
Last one have few benefits:
- It's easier to review PRs having the whole context, and not just seeing some part of bigger object
- It's easier to find string from
t()
function in the translations
But also you could mix up login
and login.title
and destroy the object without even noticing it.
- https://dev.to/omaiboroda/three-ways-to-name-i18n-translation-keys-2fed
- https://medium.com/frontmen/web-internationalisation-i18n-lessons-ive-learned-the-hard-way-438a3e157e0
- https://lokalise.com/blog/translation-keys-naming-and-organizing/
- https://phrase.com/blog/posts/ruby-lessons-learned-naming-and-managing-rails-i18n-keys/
Top comments (0)