Which are good strategies for organizing localization files for trans() in Laravel 5.x?

Question

This is a question about methodology and suggested practices. I know it is not strictly attached to the framework and not even PHP, and the answer might be "its up to you". But my concern is about best practices and methodology, as there usually exists a best approach for a certain context.

I would like to know which are the best practices for key naming for the trans() function of Laravel 5.1 ?

Considering that built-in Laravel translations are stored into an array, my concern is which hirearchy allows me to achieve the following goals:

consistency: So I minimize the possibility of using different words for the same meaning, or creating many different keys that end up having the same translation (like common words).

reusability: So I minimize the overall translation files size and translate as less as possible, and preserve flexibility.

readability: So translators can identify the purpose of the key even under lack of the translation value.

organization: So developer can easily remember the full key path and minimize checking the transalation files each time.

---

To give an example, lets say I want to name a successful alert for User model update, for a management profile. Possible approaches are:

trans('manager.user.update.alert.sucess')

trans('alerts.success.manager.user.update')

trans('manager.user.alert.update.success')

trans('alert.the_user_was_updated_successfully')

Update

By Nov-2016, it looks like Laravel 5.4 is introducing a JSON based translation mechanism that might simplify translation files. Still, caring for smart file structure and well organized texts are a plus.

Answer 1

My suggestion would be to use the parametrized translation option in Laravel.

I would suggest having a structure like this:

For content that is generic and can be reused:

trans('messages.alerts.update.success', ['item' => 'User']);   // results in: 'User has successfully been updated'
trans('messages.alerts.update.success.default');               // results in: 'Updated was successfull.'

For content that is strictly connected to a specific area/problem... (manager in this case):

trans('manager.alerts.update.user.success');   // results in: 'User has successfully been updated'

or

trans('manager.alerts.update.success', ['item' => 'User']);   // results in: 'User has successfully been updated'
trans('manager.alerts.update.success.default');               // results in: 'Updated was successfull.'

The thinking is that for something that is specific for the manager like having a update-successfull message that is likely to be different than other update-successfull messages that you should start with something specific like: manager.alerts.... In generic cases (where the same message could be used in multiple use-cases) You should start with something generic like messages.alerts.update....

Naming like trans('alert.the_user_was_updated_successfully') should be avoided in my opinion because You could have a BIG problem when you want to change a message. The key would than still reflect the old value while the value would be new.

Regarding Your goals:

consistency and reusability: A certain amount of content will be duplicated. That cannot be avoided. However this problem can be minimized by structuring content and by having a file(s) with common words and phrases eg. commons.words commons.phrases or 2 files (words, and phrases) with a few categories. Example: commons.time.day , commons.hello_world ...

readability: This will be a problem unless you give the translator a file that already has all of its values (in the default or starting language from which he/she can translate from). I really don't see why you wouldn't have an initial translation/content.

organization: You have to try and think like you would in the skin of a developer. If you are trying to find something specific you will thing and try to find something something under that specific subject (manager.alerts.... in this case) but if You are searching for something more generic you are more likely to search for something generic (messages.alerts.... in this case)

I have a similar issue and have posted a question about it. Unfortunately there has also not been much interest in the subject.