[docs-only] Add a how to in dev docs for translations in ocis

docs/services/general-info/add-translations.md

@@ -0,0 +1,106 @@
+---
+title: Add Translations
+date: 2023-12-19T00: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:
+
+* Independent of [ownCloud Web](https://app.transifex.com/owncloud-org/owncloud-web/translate/) on Transifex.
+* Are located in the [ownCloud](https://app.transifex.com/owncloud-org/owncloud/translate) Transifex Project.
+* 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.
+
+Translations are automatically synced on a daily basis in the night.
+
+## Implementing ocis Translations
+
+The implementation example is a guide and shall show how to do it. You can derive at any time according 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 `"github.com/owncloud/ocis/v2/ocis-pkg/l10n"` where required in\
+  `services/<service-name>/pkg/service/...<file>.go`.
+
+* 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:r:ocis-<service-name>]
+  file_filter = locale/<lang>/LC_MESSAGES/<service-name>.po
+  minimum_perc = 75
+  source_file = <service-name>.pot
+  source_lang = en
+  type = PO
+  ```
+
+* Create a go file like `templates.go` in `ocis/services/<service-name>/pkg/service` that will define your translation sources like the following:
+  ```
+  // available templates
+  var (
+  	YourVar = Template{
+  		Subject: l10n.Template("Context string"),
+  		Message: l10n.Template("Translation String"),
+  	}
+  var (
+  ...
+  
+  // Template is the data structure for translations
+  type Template struct {
+  	Subject string
+  	Message string
+  }
+  ```
+
+* In the `Makefile` in the **ocis root**, add in the following section the service you want to synchroize translations with Transifex:
+  ```
+  # add a service here when it uses transifex
+  L10N_MODULES := \
+  	services/notifications \
+  	services/userlog \
+  	services/graph \
+  	services/<service-name>
+  ```
+
+* In the `Makefile` of the **`<service-name>`** add:\
+  _At the beginnig:_
+  ```
+  # 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 \
+  	ocis/services/<service-name>/pkg/service/templates.go
+
+  .PHONY: l10n-write
+  l10n-write:
+
+  .PHONY: l10n-clean
+  l10n-clean:
+  	rm -f $(TEMPLATE_FILE);
+  ```