From 737d8d1c7c044905c22e4ed735f7782589cf1f80 Mon Sep 17 00:00:00 2001
From: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Date: Fri, 22 Nov 2019 14:47:19 +0000
Subject: [PATCH] Bug 24068: (RM follow-up) Enhance the POD

Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
---
 Koha/Template/Plugin/I18N.pm | 48 +++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/Koha/Template/Plugin/I18N.pm b/Koha/Template/Plugin/I18N.pm
index 37ef1ea5ec..919d3bc467 100644
--- a/Koha/Template/Plugin/I18N.pm
+++ b/Koha/Template/Plugin/I18N.pm
@@ -30,11 +30,26 @@ Koha::Template::Plugin::I18N - Translate strings in templates
 
 =head1 SYNOPSIS
 
+    [% PROCESS 'i18n.inc' %]
+
+    . . .
+
+    [% I18N.t("Hello!") %]
+    [% I18N.tx("Hello {name}", { name = name }) %]
+    [% I18N.tn("Hello friend", "Hello friends", count) %]
+    [% I18N.tnx("Hello my {count} friend", "Hello my {count} friends", count, { count = count }) %]
+    [% I18N.tp('verb', 'Item') # to order %]
+    [% I18N.tnp('bibliographic material', "item", "items", count) %]
+    [% I18N.tnpx('bibliographic material', "{count} item", "{count} items", count, { count = count }) %]
+
 Do not use this plugin directly. Add the following directive
 
     [% PROCESS 'i18n.inc' %]
 
-and use the macros defined here
+and use the macros defined.
+
+See: https://wiki.koha-community.org/wiki/Internationalization,_plural_forms,_context,_and_more_(RFC)
+for further context.
 
 =head1 METHODS
 
@@ -42,6 +57,9 @@ and use the macros defined here
 
     [% I18N.t("hello") %]
 
+Translate - The simplest type of translatable string where
+there are no variables and not pluralisations to consider.
+
 =cut
 
 sub t {
@@ -53,6 +71,9 @@ sub t {
 
     [% I18N.tx("hello {name}", { name = name }) %]
 
+Translate with variable - A translatable string that
+includes a variable
+
 =cut
 
 sub tx {
@@ -64,6 +85,9 @@ sub tx {
 
     [% I18N.tn("item", "items", count) %]
 
+Translate with plural - A translatable string that needs
+singular and plural forms
+
 =cut
 
 sub tn {
@@ -75,6 +99,9 @@ sub tn {
 
     [% I18N.tnx("{count} item", "{count} items", count, { count = count }) %]
 
+Translate with plural and variable - A translatable string
+that needs singular and plural forms and includes a variable
+
 =cut
 
 sub tnx {
@@ -97,6 +124,14 @@ sub txn {
 
     [% I18N.tp("context", "hello") %]
 
+Translate with context - A translatable string where a
+context hint would be helpful to translators.
+
+An example would be where in english a single word may be
+be used as both a verb and a noun. You may want to add a
+note to distinguish this particular use case so translators
+can understand the context correctly.
+
 =cut
 
 sub tp {
@@ -108,6 +143,9 @@ sub tp {
 
     [% I18N.tpx("context", "hello {name}", { name = name }) %]
 
+Translate with context and variable - A translatable string
+that needs both a contextual hint and includes a variable.
+
 =cut
 
 sub tpx {
@@ -119,6 +157,10 @@ sub tpx {
 
     [% I18N.tnp("context", "item", "items", count) %]
 
+Translate with context and plural - A translatable string
+that needs both a contextual hints and singular and plural
+forms.
+
 =cut
 
 sub tnp {
@@ -130,6 +172,10 @@ sub tnp {
 
     [% I18N.tnpx("context", "{count} item", "{count} items", count, { count = count }) %]
 
+Translate with context, plural and variables - A translatable
+string that needs contextual hints, singular and plural forms
+and also includes variables.
+
 =cut
 
 sub tnpx {
-- 
2.39.5