Translation in Mapbender3

Mapbender3 uses the translator service which is a Symfony component. You get more information at the Symfony Translation Documentation and Translator Class Documentation .

In the code you use the function trans to translate a text into another language.

Example how the function trans can be used in a Twig template:

{% block title %}{{ application.title | trans }}{% endblock %}

or

{% trans %}{{ application.title }}{% endtrans %}

Example for PHP:

echo $translator->trans('Hello World');

yml-files for translations

The translations can be stored in different formats. We use yml-format for Mapbender3.

We use place holder for every text e.g. mb.core.featureinfo.popup.btn.ok. Like this you can define different translations for the same word which occurs in different modules.

We translate the place holder to different languages. English is the default language that we provide. It is also defined as the fallback language in the parameters.yml file. The fallback language will be used if you define a language in parameters.yml that does not exist.

This is how a translation file messages.de.yml for German translation could look like.

mb:
  core:
    featureinfo:
      error:
        nolayer: 'Informationsebene existiert nicht.'
        unknownoption: 'Unbekannte Option %key% für %namespace%.%widgetname%.'
        noresult: 'kein Ergebnis'
      popup:
        btn:
          ok: Schließen
      class:
        title: Information
        description: Information
      tag:
        featureinfo: Information
        feature: Objekt
        info: Info
        dialog: Dialog
    aboutdialog:
      content:
        versionprefix: Version
        learnmore: 'Lernen Sie Mapbender3 kennen '
        linktitle: 'Besuchen Sie die offizielle Mapbender3 Webseite.'
        website: '- zur Webseite'
        .....

Notice: Each time you create a new translation resource you have to clear your cache.

app/console cache:clear

How can you activate translation?

Activate your default locale in the configuration file app/config/parameters.yml

fallback_locale:   en
locale:            de

Check whether translations (yml-files) for your language exist

  • mapbender/src/Mapbender/CoreBundle/Resources/translations/
  • mapbender/src/Mapbender/ManagerBundle/Resources/translations/
  • mapbender/src/Mapbender/PrintBundle/Resources/translations/
  • mapbender/src/Mapbender/WmcBundle/Resources/translations/
  • mapbender/src/Mapbender/WmsBundle/Resources/translations/
  • fom/src/FOM/CoreBundle/Resources/translations/
  • fom/src/FOM/ManagerBundle/Resources/translations/
  • fom/src/FOM/UserBundle/Resources/translations/
  • ...

Create yml-files for your language

If your language is not translated yet, it is easy to add a new language.

  • Check the translation directories and create a new file by copying the English locale (messages.en.yml)
  • translate
  • set locale in your parameters.yml to the new language
  • clear your cache
  • if everything is fine with your new language give the files to the Mapbender3 community - best would be a pull request or send the files to mapbender@osgeo.org

Naming conventions and locations

Symfony looks for translation files in the following directories in the following order:

  • the <kernel root directory>/Resources/translations
  • the <kernel root directory>/Resources/<bundle name>/translations
  • Resources/translations/ directory of the bundle.

Bundle translations can overwrite translations of the other directories.

Naming

The naming convention is domain.locale.loader.

  • domain - we use the default domain messages
  • locale - locale that the translations is made for (e.g. de, de_DE);
  • loader - defines the loader to load and parse the file. We use YAML

Share your translations with the Mapbender3 community!

Supporting more and more language would be great for Mapbender3. The Mapbender project would be happy if you could share your translations with the community.

This is what you have to do:

  • Option 1: send the new yml-files for your language to the Mapbender developer (mapbender@osgeo.org) or
  • Option 2: create a pull request on GitHub.

We prefer option 2.

How to translate and make a pull request

Repositories

https://github.com/mapbender/data-source https://github.com/mapbender/map-tools/

Since Git is a distributed versioning system, it is very convenient for each developer/contributor to have a personal public copy of the “official” repository (also known as fork).

Web hosting services like GitLab or GitHub provide this option if you visit the main code repository and press the button “Fork”. This way the developer can make changes to a personal isolated repository. Then one can ask the rest of the developers to review the code and merge accordingly through a “pull request”.

After forking the official repositories, your working repositories are: https://github.com/your_id/mapbender and https://github.com/your_id/mapbender

Github - editing on GitHub

git - working on the command line

On Linux systems get the source code locally using:

git clone https://github.com/your_id/mapbender

In order to be able to get and send changes to your public repository, you need to link your local copy to your public copy. This is done automatically for you when you “git clone”. The repository that you cloned from has the alias “origin”.

In order to be able to get changes that others do to the main repository, you need to manually link to that using:

git remote add upstream https://github.com/mapbender/mapbender

On MS Windows systems, install TortoiseGit, which extends Windows Explorer to include git commands.

  1. The first thing you should do when you install Git is to set your user name and e-mail address.
git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
cd mapbender
  1. Pull any updates from upstream project (master is the equivalent of subversion trunk)
git pull upstream master

optionally check to see what has changed.

git diff messages.de.yml
  1. add the changes into stage area
git add messages.de.yml
  1. commit changes locally
git commit -m "changed translation"
  1. send the changes to your public repository
git push origin master

At this point you can let others know that you have some changes that you want to merge, so you can use the button “Pull Request” on GitLab or GitHub. Or you can continue until you feel ready to share your changes :)

  1. Last step: pull request

In order to merge your work with the main repository, you have to make a pull request.

You can do it by logging on your github account and go to the branch you changed. Click on the New pull request green button. The changes you made previously while appear.

You can review and comment your request before submitting. To submit, click on the Create pull request green button. Then, you’re done ! Good job !

More information about Github pull request here: https://help.github.com/articles/using-pull-requests/

Working with files:

to add a file

cd <dir>

create a file

git add <file>
git commit -m "commit message"
git push origin master