From 715e62b13d48e9e3384659b91b4b6cf8b9fa209e Mon Sep 17 00:00:00 2001 From: mmattel Date: Wed, 19 Apr 2023 19:08:09 +0200 Subject: [PATCH 1/4] update readme --- services/notifications/README.md | 58 ++++++++++++++------------------ 1 file changed, 26 insertions(+), 32 deletions(-) diff --git a/services/notifications/README.md b/services/notifications/README.md index 81b25c4b9..6e5590f2d 100644 --- a/services/notifications/README.md +++ b/services/notifications/README.md @@ -4,25 +4,23 @@ The notification service is responsible for sending emails to users informing th ## 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) +The `notifications` service has embedded email body templates. Email templates can use the placeholders `{{ .Greeting }}`, `{{ .MessageBody }}` and `{{ .CallToAction }}` which are replaced with translations when sent, see the [Translations](#translations) section for more details. Depending on the email purpose, placeholders will contain different strings. An individual translatable string is available for each purpose, finally resolved by the placeholder. Though the email subject is also part of translations, it has no placeholder as it is a mandatory email component. The embedded templates are available for all deployment scenarios. + +```text +template + placeholders + translated strings <-- source strings <-- purpose +final output +``` + +In addition, the notifications service supports custom templates. Custom email templates take precedence over the embedded ones. If a custom email template exists, the embedded templates 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 templates provided by ocis you can derive from are located in the base folder [https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates](https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates) with subfolders `shares` and `spaces`. + +- [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 │ @@ -36,28 +34,24 @@ templates │ unsharedSpace.email.body.tmpl ``` +Custom email templates referenced via `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must also be located in subfolders `shares` and `spaces` and must have the same names as the embedded templates. It is important that the names of these files and folders match the embedded ones. + +Note when having multiple instances of the notfication service, the environment variable `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must resolve to a shared storage. + ## 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: +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. +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`. +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 From b00431b7a5e82d05de53600eaf6d52eb33bb4acd Mon Sep 17 00:00:00 2001 From: mmattel Date: Wed, 19 Apr 2023 19:36:53 +0200 Subject: [PATCH 2/4] update --- services/notifications/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/services/notifications/README.md b/services/notifications/README.md index 6e5590f2d..b95a4a97a 100644 --- a/services/notifications/README.md +++ b/services/notifications/README.md @@ -13,7 +13,7 @@ template final output ``` -In addition, the notifications service supports custom templates. Custom email templates take precedence over the embedded ones. If a custom email template exists, the embedded templates 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 templates provided by ocis you can derive from are located in the base folder [https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates](https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates) with subfolders `shares` and `spaces`. +In addition, the notifications service supports custom templates. Custom email templates take precedence over the embedded ones. If a custom email template exists, the embedded templates 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. This path must be available from all instances of the notifications service, a shared storage is recommended. The source templates provided by ocis you can derive from are located in following base folder [https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates](https://github.com/owncloud/ocis/tree/master/services/notifications/pkg/email/templates) with subfolders `shares` and `spaces`. - [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) @@ -36,8 +36,6 @@ templates Custom email templates referenced via `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must also be located in subfolders `shares` and `spaces` and must have the same names as the embedded templates. It is important that the names of these files and folders match the embedded ones. -Note when having multiple instances of the notfication service, the environment variable `NOTIFICATIONS_EMAIL_TEMPLATE_PATH` must resolve to a shared storage. - ## 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. From ad1f45eecaf61dacac3ca36fbc8cea0c437340f4 Mon Sep 17 00:00:00 2001 From: mmattel Date: Wed, 19 Apr 2023 19:48:42 +0200 Subject: [PATCH 3/4] clarify transifex comments for translation strings --- services/notifications/pkg/email/templates.go | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/services/notifications/pkg/email/templates.go b/services/notifications/pkg/email/templates.go index c42f205a5..f81615217 100644 --- a/services/notifications/pkg/email/templates.go +++ b/services/notifications/pkg/email/templates.go @@ -8,23 +8,23 @@ var ( // Shares ShareCreated = MessageTemplate{ bodyTemplate: "shares/shareCreated.email.body.tmpl", - // ShareCreated email template, Subject field + // ShareCreated email template, Subject field (resolves directly) Subject: Template(`{ShareSharer} shared '{ShareFolder}' with you`), - // ShareCreated email template, Greeting field + // ShareCreated email template, resolves via {{ .Greeting }} Greeting: Template(`Hello {ShareGrantee}`), - // ShareCreated email template, Message field + // ShareCreated email template, resolves via {{ .MessageBody }} MessageBody: Template(`{ShareSharer} has shared "{ShareFolder}" with you.`), - // ShareCreated email template, CallToAction field + // ShareCreated email template, resolves via {{ .CallToAction }} CallToAction: Template(`Click here to view it: {ShareLink}`), } ShareExpired = MessageTemplate{ bodyTemplate: "shares/shareExpired.email.body.tmpl", - // ShareExpired email template, Subject field + // ShareExpired email template, Subject field (resolves directly) Subject: Template(`Share to '{ShareFolder}' expired at {ExpiredAt}`), - // ShareExpired email template, Greeting field + // ShareExpired email template, resolves via {{ .Greeting }} Greeting: Template(`Hello {ShareGrantee},`), - // ShareExpired email template, Message field + // ShareExpired email template, resolves via {{ .MessageBody }} MessageBody: Template(`Your share to {ShareFolder} has expired at {ExpiredAt} Even though this share has been revoked you still might have access through other shares and/or space memberships.`), @@ -33,37 +33,37 @@ Even though this share has been revoked you still might have access through othe // Spaces templates SharedSpace = MessageTemplate{ bodyTemplate: "spaces/sharedSpace.email.body.tmpl", - // SharedSpace email template, Subject field + // SharedSpace email template, Subject field (resolves directly) Subject: Template("{SpaceSharer} invited you to join {SpaceName}"), - // SharedSpace email template, Greeting field + // SharedSpace email template, resolves via {{ .Greeting }} Greeting: Template(`Hello {SpaceGrantee},`), - // SharedSpace email template, Message field + // SharedSpace email template, resolves via {{ .MessageBody }} MessageBody: Template(`{SpaceSharer} has invited you to join "{SpaceName}".`), - // SharedSpace email template, CallToAction field + // SharedSpace email template, resolves via {{ .CallToAction }} CallToAction: Template(`Click here to view it: {ShareLink}`), } UnsharedSpace = MessageTemplate{ bodyTemplate: "spaces/unsharedSpace.email.body.tmpl", - // UnsharedSpace email template, Subject field + // UnsharedSpace email template, Subject field (resolves directly) Subject: Template(`{SpaceSharer} removed you from {SpaceName}`), - // UnsharedSpace email template, Greeting field + // UnsharedSpace email template, resolves via {{ .Greeting }} Greeting: Template(`Hello {SpaceGrantee},`), - // UnsharedSpace email template, Message field + // UnsharedSpace email template, resolves via {{ .MessageBody }} MessageBody: Template(`{SpaceSharer} has removed you from "{SpaceName}". You might still have access through your other groups or direct membership.`), - // UnsharedSpace email template, CallToAction field + // UnsharedSpace email template, resolves via {{ .CallToAction }} CallToAction: Template(`Click here to check it: {ShareLink}`), } MembershipExpired = MessageTemplate{ bodyTemplate: "spaces/membershipExpired.email.body.tmpl", - // MembershipExpired email template, Subject field + // MembershipExpired email template, Subject field (resolves directly) Subject: Template(`Membership of '{SpaceName}' expired at {ExpiredAt}`), - // MembershipExpired email template, Greeting field + // MembershipExpired email template, resolves via {{ .Greeting }} Greeting: Template(`Hello {SpaceGrantee},`), - // MembershipExpired email template, Message field + // MembershipExpired email template, resolves via {{ .MessageBody }} MessageBody: Template(`Your membership of space {SpaceName} has expired at {ExpiredAt} Even though this membership has expired you still might have access through other shares and/or space memberships`), From d5c05c722b3fad28fe2c565128301e54247eaeec Mon Sep 17 00:00:00 2001 From: mmattel Date: Wed, 19 Apr 2023 23:01:17 +0200 Subject: [PATCH 4/4] add comma --- services/notifications/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/services/notifications/README.md b/services/notifications/README.md index b95a4a97a..755cdf191 100644 --- a/services/notifications/README.md +++ b/services/notifications/README.md @@ -1,6 +1,6 @@ # Notification -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. +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