Skip to content

Latest commit

 

History

History
74 lines (49 loc) · 4.84 KB

I18N.md

File metadata and controls

74 lines (49 loc) · 4.84 KB

Back -> I18N documentation

Internationalization (i18n)

This app comes with out of the box support for Gettext, if it's installed on the server (it often is, but if not, sudo apt-get install gettext should do it). By default, the folder which contains the language files is Locale in the root of the project. This folder can be changed, but if you choose to do so, it MUST be changed in TWO locations: .env in the root folder of the project, and app/bin/i18n/config_local.sh. More info below.

All internationalization configuration values are defined in .env.

There are several helper scripts that automate the process. They must be run from the root folder of the project. Unfortunately, they're rather Ubuntu-specific right now. Anyway...

Helper Scripts

All scripts are in app/bin/i18n.

  • config.sh:

    • change default locale folder (if you do this, you MUST change it in the .env file in the root of the project, too)
    • change username for non-sudo user - some commands require root, and those that don't will be executed as this user

  • config_local.sh

    • in gitignore, so won't exist, but can be created
    • used for overriding the values of config.sh locally, like the non-sudo user (as this can differ from machine to machine)

  • addlang.sh

    • to be executed as root: sudo app/bin/i18n/addlang.sh
    • if locale parameter is given (i.e., sudo app/bin/i18n/addlang.sh ja_JP) the locale is installed onto the OS and a language folder is created in the app
    • if no parameter is given, script checks the subfolders in the locale folder and installs all languages it finds. Useful during deploymeny, or when setting up an app that was started by someone else - automates language installation for everything committed thus far.

  • update-potpo.sh

    • no params
    • when executed, does the following in order: recompiles the twig views according to viewsFolders value(s) in app/config/shared/root.php, extracts gettext strings from these compiled files, creates a new language template file (.pot) and updates all language .po files with new translatable strings, if any.

  • update-mo.sh

    • no params
    • when done with translating, run this to get machine objects readable by gettext and finalize translated rendering

Starter languages

The only locale included by default is en_US. See instructions below if you'd like to add more.

OOTB it contains just some bogus values which aren't even active. To see it in action, go to Standard/Views/home.twig and uncomment the trans block at the bottom. Note that for this to work, both gettext and twig/extensions need to be installed (extensions are only suggested in composer.json, and won't be pulled in by default).

Typical workflow: new app

When starting a new multi-language app:

  1. Decide which languages it will need
  2. Set up REGULAR_USER value in app/bin/i18n/config_local.sh. Recommendation: use same user which executes PHP code.
  3. Run sudo app/bin/i18n/addlang.sh XXXX for language you'll need, where XXXX is each of the locales. Use real locale codes (e.g. ja_JP, etc.)
  4. Use the {% trans %} block in Twig templates to mark translatable strings. More info here.
  5. Whenever you write new Twig templates or translatable strings, re-run app/bin/i18n/update-potpo.sh, translate, and then app/bin/i18n/update-mo.sh
  6. Always commit all language files

When starting from an app made by someone else, as above:

  1. Clone and set up as usual (make a DB etc.)
  2. Set up REGULAR_USER value in app/bin/i18n/config_local.sh. Recommendation: use same user which executes PHP code.
  3. Run sudo app/bin/i18n/addlang.sh. This will auto-generate all language folders
  4. Get to work. Use the {% trans %} block in Twig templates to mark translatable strings. More info here.
  5. Always commit all language files

Language Switcher

The implementation of a language switcher is up to you. Take a look in app/config/config_web.php for how the domain (the language) gets switched out, then utilize it. Use a param in the router to switch it in the session, then read from session and put into domain settings. Or use a locale as a subdomain in the URL and switch based on that. Bottom line, implementing a switcher is outside the scope of a starter app.

More info

Todo

  • GUI for using helper scripts?
  • GUI for editing .po files?
  • More Linux-agnostic helper scripts, for more distros (not interested in Windows or OS X)