Added an example application with documentation (#72)

* Added an example with explanation to "example/"

* Inserted example into github tests

* Test for fixing Makefile

* Added implicit compile rule explicitly

* Added missing "return 0"

* Mention example in main README.md

* Fixed typo

* Make "make example" more robsu

.github/workflows/ci.yml

@@ -29,4 +29,6 @@ jobs:
       - run: npm i lv_i18n -s
       - run: cd test/c ; make test-deps
       - run: make test
+      - run: cd example && make example && ./main
+      - run: cd example && make example-optimized && ./main
 

README.md

@@ -173,6 +173,12 @@ To change a text id in the `yml` files use:
 lv_i18n rename -t src/i18n/*.yml --from 'Hillo wold' --to 'Hello world!'
 ```
 
+## Example application
+
+You can find a complete example application inside the `example/`
+directory. Please see [Example README](example/README.md) for more
+information.
+
 ## C API
 
 #### int lv_i18n_init(const lv_i18n_language_pack_t * langs)

example/Makefile

@@ -0,0 +1,27 @@
+example: clean compile main
+
+example-optimized: clean compile-optimized main
+
+extract:
+	../lv_i18n.js extract -s main.c -t "translations/*.yml"
+
+compile:
+	../lv_i18n.js compile -l en-GB -t "translations/*.yml" -o .
+
+compile-optimized:
+	../lv_i18n.js compile --optimize -l en-GB -t "translations/*.yml" -o .
+
+main.o: main.c
+	$(CC) -c -o main.o main.c
+
+lv_i18n.o: lv_i18n.c
+	$(CC) -c -o lv_i18n.o lv_i18n.c
+
+main: main.o lv_i18n.o
+	$(CC) -o main main.o lv_i18n.o
+
+clean:
+	rm -f main main.o lv_i18n.o
+
+distclean: clean
+	rm -f lv_i18n.c lv_i18n.h *~

example/README.md

@@ -0,0 +1,67 @@
+Example for lv_i18n
+===================
+
+This directory contains a small example to demonstrate the use of
+lv_i18n. The source code of the C program using translated text with
+lv_i18n is "main.c" and the translations can be found in
+"translations/".
+
+## Create the lv_i18n library
+
+There are two versions: standard and optimized (using lv_i18n with
+--optimize). First create the lv_i18n library by using the available
+translations with::
+
+```sh
+make compile
+```
+
+This will create lv_i18n.h and lv_i18n.c in the current directory
+containing the library code and the translations. For the optimized
+case, use::
+
+```sh
+make compile-optimized
+```
+
+## Compile the sample program
+
+Then use the following command to compile your application in main.c
+together with the created lv_i18n library and translations::
+
+```sh
+make main
+```
+
+## Execute the application
+
+Execute your application with
+
+```sh
+./main
+```
+
+It will use lv_i18n to printf various strings and their associated
+translations. It will do this for the language pack "en-GB" (default)
+and "ru-RU". So you should see, which key gets translated and how the
+fallback to the default language works.
+
+## Extending the application
+
+The text "This is a new text" in main.c is not yet part of the
+translation and is an example on how to extend your program with new
+texts. Without the follwing work, this text is not found in the
+translation table, and therefore used unchanged/untranslated.
+
+If you added new texts to your application, you muste execute
+
+```sh
+make extract
+```
+
+to extract new texts from your main.c and add it to the translation
+files. Please the edit translations/*.yml to see, that the new key was
+added and implement a proper translation for "en-GB" and "ru-RU".
+
+Then follow above to "make compile" and "make main" to compile the
+library and application and see the new key being translated.

example/main.c

@@ -0,0 +1,32 @@
+#include <stdio.h>
+#include "lv_i18n.h"
+
+void use_i18n(void)
+{
+  printf("%s\t%s\n", "s_en_only", _("s_en_only"));
+  printf("%s\t%s\n", "s_translated", _("s_translated"));
+  printf("%s\t%s\n", "s_untranslated", _("s_untranslated"));
+  printf("%s\t%s\n", "This is a new text", _("This is a new text"));
+  for(int i=0; i<10;i++)
+    {
+      printf("%s\t%d ", "p_i_have_dogs", i);
+      printf(_p("p_i_have_dogs", i), i);
+      printf("\n");
+    }
+}
+
+int main(void)
+{
+  lv_i18n_init(lv_i18n_language_pack);
+
+  lv_i18n_set_locale("en-GB");
+  puts("en-GB:");
+  use_i18n();
+
+  lv_i18n_set_locale("ru-RU");
+  puts("ru-RU:");
+  use_i18n();
+
+  return 0;
+}
+

example/translations/en-GB.yml

@@ -0,0 +1,7 @@
+en-GB:
+  s_en_only: english only
+  s_translated: s translated
+  s_untranslated: ~
+  p_i_have_dogs:
+    one: I have %d dog
+    other: I have %d dogs

example/translations/ru-RU.yml

@@ -0,0 +1,9 @@
+ru-RU:
+  s_en_only: ~
+  s_translated: s переведено
+  s_untranslated: ~
+  p_i_have_dogs:
+    one: У меня %d собакен
+    few: У меня %d собакена
+    many: У меня %d собакенов
+    other: ~