Make Emails translatable via transifex #6025

changelog/unreleased/make-emails-translatable-via-transifex.md

@@ -0,0 +1,9 @@
+Enhancement: Notifications
+
+Make Emails translatable via transifex
+The transifex translation add in to the email templates.
+The optional environment variable NOTIFICATIONS_TRANSLATION_PATH added to config.
+The optional global environment variable OCIS_TRANSLATION_PATH added to notifications and userlog config.
+
+https://github.com/owncloud/ocis/pull/6038
+https://github.com/owncloud/ocis/issues/6025

services/notifications/Makefile

@@ -1,6 +1,10 @@
 SHELL := bash
 NAME := notifications
 
+# Where to write the files generated by this makefile.
+OUTPUT_DIR = ./pkg/email/l10n
+TEMPLATE_FILE = ./pkg/email/l10n/notifications.pot
+
 include ../../.make/recursion.mk
 
 ############ tooling ############
@@ -29,6 +33,26 @@ ci-go-generate: # CI runs ci-node-generate automatically before this target
 .PHONY: ci-node-generate
 ci-node-generate:
 
+############ translations ########
+.PHONY: l10n-pull
+l10n-pull:
+	cd $(OUTPUT_DIR) && tx pull -a --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)/notifications.pot --keyword=Template --add-comments -s pkg/email/l10n/templates.go
+
+.PHONY: l10n-write
+l10n-write:
+
+.PHONY: l10n-clean
+l10n-clean:
+	rm -f $(TEMPLATE_FILE);
+
 ############ licenses ############
 .PHONY: ci-node-check-licenses
 ci-node-check-licenses:

services/notifications/README.md

@@ -2,3 +2,66 @@
 
 The notification service is responsible for sending emails to users informing them about events that happened. To do this it hooks into the event system and listens for certain events that the users need to be informed about.
 
+## Email Notification Templates
+
+The `notifications` service has embedded email body templates.
+The email templates contain placeholders `{{ .Greeting }}`, `{{ .MessageBody }}`, `{{ .CallToAction }}` that are
+replaced with translations, see the [Translations](#translations) section.
+These embedded templates are available for all deployment scenarios. In addition, the service supports custom
+templates.
+The custom email template takes precedence over the embedded one. If a custom email template exists, the embedded ones
+are not used. To configure custom email templates,
+the `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` environment variable needs to point to a base folder that will contain the email
+templates. The source template files provided by ocis are located
+in [https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates](https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates) in the `shares`
+and `spaces` subfolders:
+[shares/shareCreated.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/shares/shareCreated.email.body.tmpl)
+[shares/shareExpired.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/shares/shareExpired.email.body.tmpl)
+[spaces/membershipExpired.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/membershipExpired.email.body.tmpl)
+[spaces/sharedSpace.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/sharedSpace.email.body.tmpl)
+[spaces/unsharedSpace.email.body.tmpl](https://github.com/owncloud/ocis/blob/master/services/notifications/pkg/email/templates/spaces/unsharedSpace.email.body.tmpl)
+
+Custom Email templates referenced via `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must be located in subfolders `shares`
+and `spaces` and have the same names as the embedded templates. This naming must match the embedded ones.
+```text
+templates
+│
+└───shares
+│   │   shareCreated.email.body.tmpl
+│   │   shareExpired.email.body.tmpl
+│
+└───spaces
+    │   membershipExpired.email.body.tmpl
+    │   sharedSpace.email.body.tmpl
+    │   unsharedSpace.email.body.tmpl
+```
+
+## Translations
+
+The `notifications` service has embedded translations sourced via transifex to provide a basic set of translated languages.
+These embedded translations are available for all deployment scenarios. In addition, the service supports custom
+translations, though it is currently not possible to just add custom translations to embedded ones. If custom
+translations are configured, the embedded ones are not used. To configure custom translations,
+the `NOTIFICATIONS_TRANSLATION_PATH` environment variable needs to point to a base folder that will contain the translation
+files. This path must be available from all instances of the notifications service, a shared storage is recommended.
+Translation files must be of type  [.po](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html#PO-Files)
+or [.mo](https://www.gnu.org/software/gettext/manual/html_node/Binaries.html). For each language, the filename needs to
+be `translations.po` (or `translations.mo`) and stored in a folder structure defining the language code. In general the path/name
+pattern for a translation file needs to be:
+
+```text
+{NOTIFICATIONS_TRANSLATION_PATH}/{language-code}/LC_MESSAGES/translations.po
+```
+
+The language code pattern is composed of `language[_territory]` where  `language` is the base language and `_territory`
+is optional and defines a country.
+
+For example, for the language `de_DE`, one needs to place the corresponding translation files
+to `{NOTIFICATIONS_TRANSLATION_PATH}/de_DE/LC_MESSAGES/translations.po`.
+
+### Translation Rules
+
+*   If a requested language code is not available, the service tries to fall back to the base language if available.
+For example, if `de_DE` is not available, the service tries to fall back to translations in the `de` folder.
+*   If the base language `de` is also not available, the service falls back to the system's default English (`en`),
+which is the source of the texts provided by the code.

services/notifications/pkg/config/config.go

@@ -28,6 +28,7 @@ type Notifications struct {
 	Events            Events                `yaml:"events"`
 	MachineAuthAPIKey string                `yaml:"machine_auth_api_key" env:"OCIS_MACHINE_AUTH_API_KEY;NOTIFICATIONS_MACHINE_AUTH_API_KEY" desc:"Machine auth API key used to validate internal requests necessary to access resources from other services."`
 	EmailTemplatePath string                `yaml:"email_template_path" env:"OCIS_EMAIL_TEMPLATE_PATH;NOTIFICATIONS_EMAIL_TEMPLATE_PATH" desc:"Path to Email notification templates overriding embedded ones."`
+	TranslationPath   string                `yaml:"translation_path" env:"OCIS_TRANSLATION_PATH,NOTIFICATIONS_TRANSLATION_PATH" desc:"(optional) Set this to a path with custom translations to overwrite the builtin translations. Note that file and folder naming rules apply, see the documentation for more details."`
 	RevaGateway       string                `yaml:"reva_gateway" env:"OCIS_REVA_GATEWAY;REVA_GATEWAY" desc:"CS3 gateway used to look up user metadata" deprecationVersion:"3.0" removalVersion:"3.1" deprecationInfo:"REVA_GATEWAY changing name for consistency" deprecationReplacement:"OCIS_REVA_GATEWAY"`
 	GRPCClientTLS     *shared.GRPCClientTLS `yaml:"grpc_client_tls"`
 }

services/notifications/pkg/email/composer.go

@@ -0,0 +1,41 @@
+package email
+
+import (
+	"embed"
+	"io/fs"
+	"strings"
+
+	"github.com/leonelquinteros/gotext"
+)
+
+var (
+	//go:embed l10n/locale
+	_translationFS embed.FS
+	_domain        = "notifications"
+)
+
+// ComposeMessage renders the message based on template
+func ComposeMessage(template, locale string, path string) string {
+	raw := loadTemplate(template, locale, path)
+	return replacePlaceholders(raw)
+}
+
+func loadTemplate(template, locale string, path string) string {
+	// Create Locale with library path and language code and load default domain
+	var l *gotext.Locale
+	if path == "" {
+		filesystem, _ := fs.Sub(_translationFS, "l10n/locale")
+		l = gotext.NewLocaleFS(locale, filesystem)
+	} else { // use custom path instead
+		l = gotext.NewLocale(path, locale)
+	}
+	l.AddDomain(_domain) // make domain configurable only if needed
+	return l.Get(template)
+}
+
+func replacePlaceholders(raw string) string {
+	for o, n := range _placeholders {
+		raw = strings.ReplaceAll(raw, o, n)
+	}
+	return raw
+}

services/notifications/pkg/email/email.go

@@ -1,8 +1,12 @@
+// Package email implements utility for rendering the Email.
+//
+// The email package supports transifex translation for email templates.
 package email
 
 import (
 	"bytes"
 	"embed"
+	"html"
 	"html/template"
 	"path/filepath"
 )
@@ -13,22 +17,63 @@ var (
 )
 
 // RenderEmailTemplate renders the email template for a new share
-func RenderEmailTemplate(templateName string, templateVariables map[string]string, emailTemplatePath string) (string, error) {
+func RenderEmailTemplate(mt MessageTemplate, locale string, emailTemplatePath string, translationPath string, vars map[string]interface{}) (string, string, error) {
+	// translate a message
+	mt.Subject = ComposeMessage(mt.Subject, locale, translationPath)
+	mt.Greeting = ComposeMessage(mt.Greeting, locale, translationPath)
+	mt.MessageBody = ComposeMessage(mt.MessageBody, locale, translationPath)
+	mt.CallToAction = ComposeMessage(mt.CallToAction, locale, translationPath)
+
+	// replace the body email placeholders with the values
+	subject, err := executeRaw(mt.Subject, vars)
+	if err != nil {
+		return "", "", err
+	}
+
+	// replace the body email template placeholders with the translated template
+	rawBody, err := executeEmailTemplate(emailTemplatePath, mt)
+	if err != nil {
+		return "", "", err
+	}
+	// replace the body email placeholders with the values
+	body, err := executeRaw(rawBody, vars)
+	if err != nil {
+		return "", "", err
+	}
+	return subject, body, nil
+}
+
+func executeEmailTemplate(emailTemplatePath string, mt MessageTemplate) (string, error) {
 	var err error
 	var tpl *template.Template
 	// try to lookup the files in the filesystem
-	tpl, err = template.ParseFiles(filepath.Join(emailTemplatePath, templateName))
+	tpl, err = template.ParseFiles(filepath.Join(emailTemplatePath, mt.bodyTemplate))
 	if err != nil {
 		// template has not been found in the fs, or path has not been specified => use embed templates
-		tpl, err = template.ParseFS(templatesFS, filepath.Join("templates/", templateName))
+		tpl, err = template.ParseFS(templatesFS, filepath.Join("templates/", mt.bodyTemplate))
 		if err != nil {
 			return "", err
 		}
 	}
-	var writer bytes.Buffer
-	err = tpl.Execute(&writer, templateVariables)
+	str, err := executeTemplate(tpl, mt)
 	if err != nil {
 		return "", err
 	}
+	return html.UnescapeString(str), err
+}
+
+func executeRaw(raw string, vars map[string]interface{}) (string, error) {
+	tpl, err := template.New("").Parse(raw)
+	if err != nil {
+		return "", err
+	}
+	return executeTemplate(tpl, vars)
+}
+
+func executeTemplate(tpl *template.Template, vars any) (string, error) {
+	var writer bytes.Buffer
+	if err := tpl.Execute(&writer, vars); err != nil {
+		return "", err
+	}
 	return writer.String(), nil
 }

services/notifications/pkg/email/l10n/.tx/config

@@ -0,0 +1,9 @@
+[main]
+host = https://www.transifex.com
+
+[o:owncloud-org:p:owncloud:r:ocis-notifications]
+file_filter = locale/<lang>/LC_MESSAGES/notifications.po
+minimum_perc = 75
+source_file = notifications.pot
+source_lang = en
+type = PO

services/notifications/pkg/email/l10n/locale/de_DE/LC_MESSAGES/notifications.po

@@ -0,0 +1,102 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid   ""
+msgstr  "Project-Id-Version: \n"
+        "Report-Msgid-Bugs-To: EMAIL\n"
+        "POT-Creation-Date: 2023-04-14 16:58+0200\n"
+        "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+        "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+        "Language-Team: LANGUAGE <LL@li.org>\n"
+        "Language: \n"
+        "MIME-Version: 1.0\n"
+        "Content-Type: text/plain; charset=CHARSET\n"
+        "Content-Transfer-Encoding: 8bit\n"
+
+#. UnsharedSpace email template, CallToAction field
+#: pkg/email/templates.go:57
+msgid   "Click here to check it: {ShareLink}"
+msgstr  ""
+
+#. ShareCreated email template, CallToAction field
+#. SharedSpace email template, CallToAction field
+#: pkg/email/templates.go:18 pkg/email/templates.go:43
+msgid   "Click here to view it: {ShareLink}"
+msgstr  ""
+
+#. ShareCreated email template, Greeting field
+#: pkg/email/templates.go:14
+msgid   "Hello {ShareGrantee}"
+msgstr  ""
+
+#. ShareExpired email template, Greeting field
+#: pkg/email/templates.go:26
+msgid   "Hello {ShareGrantee},"
+msgstr  ""
+
+#. SharedSpace email template, Greeting field
+#. UnsharedSpace email template, Greeting field
+#. MembershipExpired email template, Greeting field
+#: pkg/email/templates.go:39 pkg/email/templates.go:51 pkg/email/templates.go:65
+msgid   "Hello {SpaceGrantee},"
+msgstr  ""
+
+#. MembershipExpired email template, Subject field
+#: pkg/email/templates.go:63
+msgid   "Membership of '{SpaceName}' expired at {ExpiredAt}"
+msgstr  ""
+
+#. ShareExpired email template, Subject field
+#: pkg/email/templates.go:24
+msgid   "Share to '{ShareFolder}' expired at {ExpiredAt}"
+msgstr  ""
+
+#. MembershipExpired email template, Message field
+#: pkg/email/templates.go:67
+msgid   "Your membership of space {SpaceName} has expired at {ExpiredAt}\n"
+        "\n"
+        "Even though this membership has expired you still might have access through other shares and/or space memberships"
+msgstr  ""
+
+#. ShareExpired email template, Message field
+#: pkg/email/templates.go:28
+msgid   "Your share to {ShareFolder} has expired at {ExpiredAt}\n"
+        "\n"
+        "Even though this share has been revoked you still might have access through other shares and/or space memberships."
+msgstr  ""
+
+#. ShareCreated email template, Message field
+#: pkg/email/templates.go:16
+msgid   "{ShareSharer} has shared \"{ShareFolder}\" with you."
+msgstr  ""
+
+#. ShareCreated email template, Subject field
+#: pkg/email/templates.go:12
+msgid   "{ShareSharer} shared '{ShareFolder}' with you"
+msgstr  ""
+
+#. SharedSpace email template, Message field
+#: pkg/email/templates.go:41
+msgid   "{SpaceSharer} has invited you to join \"{SpaceName}\"."
+msgstr  ""
+
+#. UnsharedSpace email template, Message field
+#: pkg/email/templates.go:53
+msgid   "{SpaceSharer} has removed you from \"{SpaceName}\".\n"
+        "\n"
+        "You might still have access through your other groups or direct membership."
+msgstr  ""
+
+#. SharedSpace email template, Subject field
+#: pkg/email/templates.go:37
+msgid   "{SpaceSharer} invited you to join {SpaceName}"
+msgstr  ""
+
+#. UnsharedSpace email template, Subject field
+#: pkg/email/templates.go:49
+msgid   "{SpaceSharer} removed you from {SpaceName}"
+msgstr  ""
+