From b97521b8a71f223b52ac7bf9d5da7c328249d0b5 Mon Sep 17 00:00:00 2001 From: "Dr. Tilmann Bubeck" Date: Tue, 29 Oct 2024 14:21:49 +0100 Subject: [PATCH] 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 | 2 + README.md | 6 +++ example/Makefile | 27 ++++++++++++++ example/README.md | 67 ++++++++++++++++++++++++++++++++++ example/main.c | 32 ++++++++++++++++ example/translations/en-GB.yml | 7 ++++ example/translations/ru-RU.yml | 9 +++++ 7 files changed, 150 insertions(+) create mode 100644 example/Makefile create mode 100644 example/README.md create mode 100644 example/main.c create mode 100644 example/translations/en-GB.yml create mode 100644 example/translations/ru-RU.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index aaeb2e6..83e7b8e 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/README.md b/README.md index 8eee37c..ad3436e 100644 --- a/README.md +++ b/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) diff --git a/example/Makefile b/example/Makefile new file mode 100644 index 0000000..9ec18d4 --- /dev/null +++ b/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 *~ diff --git a/example/README.md b/example/README.md new file mode 100644 index 0000000..ddb3dc4 --- /dev/null +++ b/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. diff --git a/example/main.c b/example/main.c new file mode 100644 index 0000000..d90bc68 --- /dev/null +++ b/example/main.c @@ -0,0 +1,32 @@ +#include +#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; +} + diff --git a/example/translations/en-GB.yml b/example/translations/en-GB.yml new file mode 100644 index 0000000..f39def1 --- /dev/null +++ b/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 diff --git a/example/translations/ru-RU.yml b/example/translations/ru-RU.yml new file mode 100644 index 0000000..4b48bf5 --- /dev/null +++ b/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: ~