---
title: Add Translations
date: 2024-04-08T00:00:00+00:00
weight: 20
geekdocRepo: https://github.com/owncloud/ocis
geekdocEditPath: edit/master/docs/services/general-info
geekdocFilePath: add-translations.md
geekdocCollapseSection: true
---

Services can have texts that need to be translated. These translations will be shown in the ownCloud Web UI. Compared to web, these translations:

* Are located in the same Transifex project as the web, which is named [ownCloud Web](https://app.transifex.com/owncloud-org/owncloud-web/translate/).
* Have a name starting with `ocis-` for ease of identification.

The process for _synchronisation_ with Transifex is already setup and nothing needs to be done here. For any translation, it is necessary to set it up in the respective service and tell to sync it.

**IMPORTANT**\
Translations are automatically synced on a daily basis in the night. To do so, there is an own repo that covers the process for ALL translations from all configured repos: [translation-sync](https://github.com/owncloud/translation-sync). If there is a manual "emergency" sync necessary, you only need to trigger [drone](https://drone.owncloud.com/owncloud/translation-sync) via cli

```bash
drone cron exec owncloud/translation-sync nightly
```
Note that you need to be logged on in drone to execute the command.

## Implementing ocis Translations

The implementation example is a guide and shall show how to do it. You can derive at any time according to your needs.

Note that paths are examples and can be adapted based on requirements.\
Replace `<service-name>` with the name of the respective service.\
Translations have a `context` and a `translatable string`. The context is shown on Transifex but not translated and helps translators to get a context for the string to be translated.

* Add the `OCIS_DEFAULT_LANGUAGE` envvar in `services/<service-name>/pkg/config/config.go`.\
  For details see the userlog or notifications service code.

* Add the `<SERVICE_NAME>_TRANSLATION_PATH` envvar in `services/<service-name>/pkg/config/config.go`.\
  For details see the userlog or notifications service code.

* Use `"github.com/owncloud/ocis/v2/ocis-pkg/l10n"` for the translation.\
  Use `l10n.Template` to define the translation string.\
  Use `l10n.NewTranslator` or `l10n.NewTranslatorFromCommonConfig` to get the translator.\
  Use `t.Get` to translate the string. See package for more advanced usage.

* Create a config in `services/<service-name>/pkg/service/l10n/.tx/config` with the following content. Note that it is important to stick with `ocis-<service-name>` to easily identify all ocis translations on Transifex:
  ```
  [main]
  host = https://www.transifex.com

  [o:owncloud-org:p:owncloud-web:r:ocis-<service-name>]
  file_filter = locale/<lang>/LC_MESSAGES/<service-name>.po
  minimum_perc = 75
  resource_name = ocis-<service-name>
  source_file = <service-name>.pot
  source_lang = en
  type = PO
  ```
  Note: o: organization, p: project, r: resource

* Create an empty file `services/<service-name>/pkg/service/l10n/locale/en/LC_MESSAGES/<service-name>.po`. This is required for ocis to build. This file will be replaced nightly with the latest translations from Transifex.

* Create a go file like `templates.go` in e.g. `ocis/services/<service-name>/pkg/service` that will define your translation sources like the following:
  ```
  // this comment will appear in transifex as context
  var yourString = l10n.Template("Translation String")
  ```

* In the `Makefile` in the **ocis root**, add in the following section the service you want to synchronize translations with Transifex:
  ```
  # add a service here when it uses transifex
  L10N_MODULES := \
  	services/notifications \
  	services/userlog \
  	services/graph \
  	services/activitylog \
  	services/<service-name>
  ```

* In the `Makefile` of the **`<service-name>`** add:\
  _At the beginning:_
  ```
  # Where to write the files generated by this makefile.
  OUTPUT_DIR = ./pkg/service/<...>/l10n
  TEMPLATE_FILE = ./pkg/service/<...>/l10n/<service-name>.pot
  ```
  _In the `.PHONY` list:_
  ```
  ############ translations ########
  .PHONY: l10n-pull
  l10n-pull:
  	cd $(OUTPUT_DIR) && tx pull --all --force --skip --minimum-perc=75

  .PHONY: l10n-push
  l10n-push:
  	cd $(OUTPUT_DIR) && tx push -s --skip

  .PHONY: l10n-read
  l10n-read: $(GO_XGETTEXT)
  	go-xgettext -o $(OUTPUT_DIR)/<service-name>.pot \
  	--keyword=l10n.Template --add-comments -s \
  	pkg/service/templates.go

  .PHONY: l10n-write
  l10n-write:

  .PHONY: l10n-clean
  l10n-clean:
  	rm -f $(TEMPLATE_FILE);
  ```

* Add Description Text to README\
  Add the full `Translations` and `Default Language` text blocks including their sub sections to the service readme. You can derive from the `activitylog` or `userlog` service for easy copy/paste.
