Noissue - Improve CMS usage documentation

README.md

Index: README.md
diff --git a/README.md b/README.md
index 113b56983c0cd77b8aebbcc07acc4988606699d3..f3276951577d7d3a1d60d7fc9d27e7df03a72414 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,27 @@ Include files should be placed into the `includes` directory of the repository.
 In the case above the contents of `includes/foo.md` or `includes/foo.tmpl` will
 be inserted (whichever is present).
 
+When writing content that needs to be translated into the different supported
+languages you can use the following syntax:
+
+    {{string_name String contents in default language}}
+
+Try to give the string a descriptive name as it will help translators.
+Optionally you can add a description for strings as well to provide even more
+context:
+
+    {{string_name[The string description] String contents}}

[Wladimir Palant, 2015/09/03 12:15:26]

You need to point out explicitly that neither the string name nor description
have any effect on the generated markup - they are merely context information
visible to translators.

[kzar, 2015/09/03 13:05:33]

Done.

+
+Finally if you find yourself using the same string multiple times in a page
+you can reduce duplication by simply omitting the description and contents
+after the first use. For example:
+
+    {{title[Title of the page] Adblock Plus - Home}}
+    {{title}}
+
+_Note: For Jinja2 templates this syntax does not work, you will need to use the
+custom Jinja2 filters and global functions as documented below._

[Wladimir Palant, 2015/09/03 12:15:26]

This section belongs under "Markdown format" - that's how Markdown files are
being localized. You can add a note under "Raw html" saying that the
localization approach there is identical to Markdown (it sort of says so
already).

[kzar, 2015/09/03 13:05:33]

Done.

+
 #### Markdown format (md) ####
 
 This format should normally be used, it allows the pages to be defined using the
@@ -248,14 +269,29 @@ The following variables can be used:
 
 Following custom filters can be used:
 
-* `translate(string, locale=None)`: retrieves a string from a locale file.
-  Unless a locale is specified the locale file matching the page name is used.
+* `translate(string, name, comment=None)`: retrieves a string from a locale file
+   for the given page name in the current language. Optionally a comment or
+   description can be specified as well.

[Wladimir Palant, 2015/09/03 12:15:26]

First parameter isn't string any more, it's default - you should point out what
it means.

[kzar, 2015/09/03 13:05:33]

Done.

 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is
   a page name it will be converted into a link to the most appropriate page
   language.
 * `toclist(html)`: extracts a list of headings from HTML code, this can be used
   to generate a table of contents.
 
+The following global functions can be used:
+
+* `get_string(name, page=None)`: retrieves a string from a locale file.
+  Unless a locale is specified the locale file matching the page name is used.

[Wladimir Palant, 2015/09/03 12:15:26]

I think you meant: "Unless a page is specified the locale file matching the name
of the current page is used."

[kzar, 2015/09/03 13:05:32]

Done.

+* `get_page_content(page, locale=None)`: returns a dictionary of the content
+  and params for the given page and locale. Locale defaults to the current one
+  if not specified. Provided keys include:
+
+```
+['localized_string_callback', 'body', 'templatedata', 'available_locales',
+ 'title', 'locale', 'head', 'source', 'localedata', 'template', 'defaultlocale',
+ 'pagedata', 'translation_ratio', 'config', 'page']

[Wladimir Palant, 2015/09/03 12:15:26]

Please don't list everything returned. In particular, things meant for internal
use and the ones identical to the current page are irrelevant. It's really:
head, body, available_locales, translation_ratio.

[kzar, 2015/09/03 13:05:33]

Done.

+```
+
 ### Static files ###
 
 Any files located in the `static` directory will be available on the server