Appearance

Internationalization ​

We want the code to be free from German-specific texts to enable non-German speakers to use the site and to make it easier for groups in other countries to use the code. The code should therefore not contain any hard-coded strings.

Translation files ​

Translations are stored in YAML format in the /translations directory. Working with the translation files should follow some general rules:

  • Changes only need to be made to the German translations, although you may change the other languages too. All missing changes can then be translated using Weblate.
  • Translation keys should not be added to the top level of the YAML file. Please add them into any of the matching subsections.
  • There are some general sections like "terminology". Keys in those sections are meant to be reused. If you need a key in a frontend component and one of these fits, please use it instead of adding a new redundant key.
  • Most other sections are related to specific components of the website. Keys in those sections should not be reused outside of that scope. For example, if you need a translation key for the store page and you find a fitting one in the baskets section, do not use it directly. Either add a similar key to the store section or, if it makes sense, move the key to a more general section.
  • Please only split up text into multiple translation keys if that is necessary for the frontend component. Otherwise, use a single translation key with placeholders. This helps translating them into languages that have a different sentence structure. For example, instead of having a string "Created at" which is concatenated with a date string in the frontend, use the placeholder "Created at {date}".
  • HTML should not be used unless necessary. If possible, use Markdown instead. There is a Markdown.vue component that allows you to render such text.

Weblate ​

We are using Weblate as a tool for translating the texts into other languages. It allows you to help translating the website without working directly with the code. The project is located at https://hosted.weblate.org/projects/foodsharing/. Our project uses German as the default language, which means that texts are translated from German into the target language. If a language is not yet listed in our project, feel free to add it.

Using translation keys in the code ​

In PHP ​

We use the Symfony TranslatorInterface to replace translation keys (given in code) with their translated values.

From JavaScript code ​

In client/src/helper/i18n.js we built a basic replacement function that imports translation resources, replaces variables if needed, and returns the translated value if one exists.
To use this function elsewhere, import the module like so:

js
import t from '@/helper/i18n'
pulseInfo(t('basket.not_active'))

As part of Vue templates ​

We use Vue I18n for translations in Vue components. You can use the $t method to translate keys directly in your templates. Example:

html
<b-button variant="primary">
  {{ $t('button.ok') }}
</b-button>

If you are translating component parameters, make sure to :bind them accordingly: :title="$t('button.clear_filter')"

As part of Twig templates (Legacy) ​

The trans filter allows passing translation keys to the translation engine from Twig files. Example:

php
{% raw %}{% embed 'components/field.twig' with {'title': 'events.bread'|trans} %}{% endraw %}
{% raw %}<h4>{{ 'dashboard.push.title'|trans }}</h4>{% endraw %}

Do not create more of these unless you really know what you're doing! You will need to be very careful with the syntax for replacing variables ({% raw %}|trans({'%name%': name}{% endraw %})).