README updated. Some unit-tests added #88.

README.markdown

@@ -106,7 +106,7 @@ Options is a proplist possibly containing:
   trans "StringValue" %}` on templates).  See README_I18N.
 
 * `blocktrans_fun` - A two-argument fun to use for translating
-  `blocktrans` blocks. This will be called once for each pair of
+  `blocktrans` blocks at compile-time. This will be called once for each pair of
   `blocktrans` block and locale specified in `blocktrans_locales`. The
   fun should take the form:
 
@@ -198,8 +198,9 @@ IOList is the rendered template.
 Same as `render/1`, but with the following options:
 
 * `translation_fun` - A fun/1 that will be used to translate strings
-  appearing inside `{% trans %}` tags. The simplest TranslationFun
-  would be `fun(Val) -> Val end`
+  appearing inside `{% trans %}` and `{% blocktrans %}` tags. The simplest
+  TranslationFun would be `fun(Val) -> Val end`. Placeholders for
+  blocktrans variable interpolation should be wrapped to `{{` and `}}`.
 
 * `locale` - A string specifying the current locale, for use with the
   `blocktrans_fun` compile-time option.

README_I18N

@@ -5,10 +5,26 @@ Erlydtl allows templates to use i18n features based on gettext. Standard po
 files can be used to generate i18ized templates. A template parser/po generator
 is also provided.
 
+Translation done by `{%trans%}`, `{%blocktrans%}` tags and by wrapping variables
+in `_(...)` construction.
+
+Translation may be applied in compile time (translated strings are embedded in
+compiled template code) or in runtime (template will query gettext server during
+template rendering). 1'st is faster in terms of template rendering time, 2'nd is
+more flexible (you may update locales without any template recompilation).
+
+In order to apply compile-time translation, you must pass `blocktrans_fun` plus
+`blocktrans_locales` (this will translate `{%blocktrans%}`) and/or `locale` (this
+translates `{%trans%}` and `_("string literal")` values) to `erlydtl:compile/3`.
+Next, you should pass `locale` option to `my_compiled_template:render/2`.
+
+If you prefer runtime translation, just don't pass `blocktrans_fun` and/or `locale`
+compilation options and add `translation_fun` option to `my_compiled_template:render/2`.
+
     1.  In order to enable i18n you first, you'll need gettext library to be
         available on your lib_path. 
 
-        Library can be downloaded from http://github.com/noss/erlang-gettext
+        Library can be downloaded from http://github.com/etnt/gettext
 
     2.  Then you'll need to add a parse target on your makefile (or the script
         used to trigger template reparsing) trans:
@@ -26,7 +42,8 @@ is also provided.
         directories where generator will search for template files including
         trans tags.
 
-    3.  Before template parsing gettext server must be running and it must be
+    3.  If you wish to translate templates at compile-time, gettext server must be
+        running before template parsing and it must be
         populated with the content of the po files. Consider adding this
         snipplet to the code before template parsing
 
@@ -44,4 +61,5 @@ is also provided.
     4.  Update strings. Edit po files on $(GETTEXT_DIR)/lang/default/$(LOCALE)/gettext.po 
         translating msgstr to the translated version of their corresponding msgstr.
 
-    5.  Generate localized templates providing locale compile option.
+    5.  Generate localized templates providing `locale` compile option or use runtime
+        translation via `translation_fun` rendering option.

tests/src/erlydtl_unittests.erl

@@ -1190,9 +1190,14 @@ tests() ->
         <<"{% blocktrans %}Hello, {{ name }}{% endblocktrans %}">>, [{name, "Mr. President"}], [{locale, "de"}],
         [{blocktrans_locales, ["de"]}, {blocktrans_fun, fun("Hello, {{ name }}", "de") -> <<"Guten tag, {{ name }}">> end}], <<"Guten tag, Mr. President">>},
        {"blocktrans with args",
-        <<"{% blocktrans with var1=foo %}{{ var1 }}{% endblocktrans %}">>, [{foo, "Hello"}], <<"Hello">>}
-       %% {"blocktrans complex not allowed",
+        <<"{% blocktrans with var1=foo %}{{ var1 }}{% endblocktrans %}">>, [{foo, "Hello"}], <<"Hello">>},
+       %% {"blocktrans complex not allowed - this should fall",
        %%  <<"{% blocktrans %}Hello{%if user%}, {{ user.name }}{%endif%}!{% endblocktrans %}">>, [], assert-raise-syntax-error}
+       {"blocktrans runtime",
+        <<"{% blocktrans with v1=foo%}Hello, {{ name }}! See {{v1}}.{%endblocktrans%}">>,
+        [{name, "Mr. President"}, {foo, <<"rubber-duck">>}],
+        [{translation_fun, fun("Hello, {{ name }}! See {{ v1 }}.") -> <<"Guten tag, {{name}}! Sehen {{    v1   }}.">> end}],
+        [], <<"Guten tag, Mr. President! Sehen rubber-duck.">>}
       ]},
      {"verbatim", [
                    {"Plain verbatim",