Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Unified Diff: README.md

Issue 29325800: Noissue - Improve CMS usage documentation (Closed)
Patch Set: Addressed Wladimir's feedback Created Sept. 3, 2015, 1:02 p.m.
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View side-by-side diff with in-line comments
Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
Index: README.md
diff --git a/README.md b/README.md
index 113b56983c0cd77b8aebbcc07acc4988606699d3..58434edf9697dc0d04ef3ae6542896e7b365fe54 100644
--- a/README.md
+++ b/README.md
@@ -210,24 +210,40 @@ tags are allowed and can be used where Markdown syntax isn't sufficient. The
extension is active and allows specifying custom attributes for the generated
HTML tags.
-Localizable strings are retrieved from the locale file with the name matching
-the page name. The following syntax can be used: `$foo$` inserts a string named
-`foo` from the locale (no HTML code or Markdown syntax allowed in the string).
-The syntax `$foo(foopage, http://example.com/)$` will work similarly but will
-look for `<a>...</a>` blocks in the string: the first will be turned into a link
-to the page `foopage`, the second will become a link to `http://example.com/`.
-
Any content between `<head>` and `</head>` tags will be inserted into the head
of the generated web page, this is meant for styles, scripts and the like.
Other pages should be linked by using their name as link target (relative links),
these links will be resolved to point to the most appropriate page language.
Embedding localizable images works the same, use the image name as image source.
+Localizable strings can be specified inline with 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}}
+
+_Note: String names and descriptions have no effect on the generated page,
+assuming string name is unique to the page. The name and description are just
+used to provide translators with additional context about the string._
+
+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}}
+
#### Raw HTML format (html) ####
This format is similar to the Markdown format but uses regular HTML syntax.
No processing is performed beyond inserting localized strings and resolving
links to pages and images. This format is mainly meant for legacy content.
+The syntax for localizable strings documented above can be used as with
+Markdown.
#### Jinja2 format (tmpl) ####
@@ -248,14 +264,28 @@ 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(default, name, comment=None)`: translates the given default string
+ for the given page name into the current language. Optionally a comment or
+ description can be specified as well.
Wladimir Palant 2015/09/03 13:37:37 What's the difference between comment and descript
kzar 2015/09/03 14:04:14 Well we seem to use both "comment" and "descriptio
* `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 page is specified the locale file matching the name of the current
+ page is used.
+* `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:
+
+```
+['head', 'body', 'available_locales', 'translation_ratio']
+```
Wladimir Palant 2015/09/03 13:37:37 Why have this as a Python list? "Provided keys inc
kzar 2015/09/03 14:04:14 Done.
+
### Static files ###
Any files located in the `static` directory will be available on the server
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld