From fa86687fa6e3724df19bb1fe76038247418426f7 Mon Sep 17 00:00:00 2001 From: peartown Date: Mar 25 2024 23:26:01 +0000 Subject: Add 'Translation hints and tips' to weblate.adoc modified: modules/ROOT/pages/weblate.adoc new file: modules/ROOT/assets/images/Weblate_create_translation.png new file: modules/ROOT/assets/images/Weblate_project_component_languages.png new file: modules/ROOT/assets/images/Weblate_project_components_list.png new file: modules/ROOT/assets/images/Weblate_project_start_newtrans.png new file: modules/ROOT/assets/images/Weblate_project_start_newtrans_langlist.png new file: modules/ROOT/assets/images/Website_translation_curlybrackets_example_cs.png new file: modules/ROOT/assets/images/Website_translation_curlybrackets_example_en.png --- diff --git a/modules/ROOT/assets/images/Weblate_create_translation.png b/modules/ROOT/assets/images/Weblate_create_translation.png new file mode 100644 index 0000000..18958b9 Binary files /dev/null and b/modules/ROOT/assets/images/Weblate_create_translation.png differ diff --git a/modules/ROOT/assets/images/Weblate_project_component_languages.png b/modules/ROOT/assets/images/Weblate_project_component_languages.png new file mode 100644 index 0000000..9ecc3e3 Binary files /dev/null and b/modules/ROOT/assets/images/Weblate_project_component_languages.png differ diff --git a/modules/ROOT/assets/images/Weblate_project_components_list.png b/modules/ROOT/assets/images/Weblate_project_components_list.png new file mode 100644 index 0000000..fd1c92b Binary files /dev/null and b/modules/ROOT/assets/images/Weblate_project_components_list.png differ diff --git a/modules/ROOT/assets/images/Weblate_project_start_newtrans.png b/modules/ROOT/assets/images/Weblate_project_start_newtrans.png new file mode 100644 index 0000000..97c0fa8 Binary files /dev/null and b/modules/ROOT/assets/images/Weblate_project_start_newtrans.png differ diff --git a/modules/ROOT/assets/images/Weblate_project_start_newtrans_langlist.png b/modules/ROOT/assets/images/Weblate_project_start_newtrans_langlist.png new file mode 100644 index 0000000..3faf3e6 Binary files /dev/null and b/modules/ROOT/assets/images/Weblate_project_start_newtrans_langlist.png differ diff --git a/modules/ROOT/assets/images/Website_translation_curlybrackets_example_cs.png b/modules/ROOT/assets/images/Website_translation_curlybrackets_example_cs.png new file mode 100644 index 0000000..866f7a2 Binary files /dev/null and b/modules/ROOT/assets/images/Website_translation_curlybrackets_example_cs.png differ diff --git a/modules/ROOT/assets/images/Website_translation_curlybrackets_example_en.png b/modules/ROOT/assets/images/Website_translation_curlybrackets_example_en.png new file mode 100644 index 0000000..22de7bd Binary files /dev/null and b/modules/ROOT/assets/images/Website_translation_curlybrackets_example_en.png differ diff --git a/modules/ROOT/pages/weblate.adoc b/modules/ROOT/pages/weblate.adoc index c398635..fe5a2f4 100644 --- a/modules/ROOT/pages/weblate.adoc +++ b/modules/ROOT/pages/weblate.adoc @@ -60,3 +60,115 @@ image:Project_search.png[] For further information about using Weblate software, please visit the official https://docs.weblate.org[Weblate Documentation]. +// This could have it's own page in the future +== Translation hints and tips + +Our primary aim for this subchapter is to provide some useful and quick information you may seek, particularly when you have just begun translating for Fedora. +It is inspired by questions received from within our community members and preserved in the "`question-and-answer`" style. + +Should you wish to see other question answered here, please xref:index.adoc#find-l10n[let us know]. + +[discrete] +=== How to start translating a project in Weblate to my language? Why I can't find my language on the list? + +When you visit a project to translate in Weblate (fig. 1) and enter one of it's components, you are presented with a list of languages (fig. 2) that doesn't have to contain all languages set and available for translation in Weblate. +The list contains languages only for which a translation of a given project/component was created. + +.A project with its translation components +image::Weblate_project_components_list.png[] + +.A component with languages listed +image::Weblate_project_component_languages.png[] + +Provided you have set a `_translated language_` in your profile setings, your language translation can be added, strictly speaking, created by clicking on the btn:[+] sign next to your language on the list (fig. 3). +If such option is not available to you, you can click btn:[Start new translation] button in the end of the list and subsequently choose your language from the list of all langauges available in Weblate (fig. 4)(fig. 5). + +.Create translation button for the Czech language +image::Weblate_create_translation.png[] + +.Start new translation page +image::Weblate_project_start_newtrans.png[] + +.Dropdown list with all available languages +image::Weblate_project_start_newtrans_langlist.png[] + +If you still cannot find your language and you expect 3 letter code, please note Weblate prefers https://docs.weblate.org/en/latest/admin/languages.html#language-code[two letter codes]. +If you are not able to find your language even after that, https://pagure.io/fedora-l10n/tickets[file a ticket]. + +[discrete] +=== Should I translate the text I find enclosed in curly brackets in the fedora-websites-3.0 project? + +No, it is not translatable and the text should be left unchanged. + +The curly brackets in the https://translate.fedoraproject.org/projects/fedora-websites-3-0/[fedora-website-3.0] translation project are used to distinguish names of (HTML) templates. +A template's content(s) is inserted (interpolated) during the website build process. +Related text interpolation facilitates localization since it enables a combination of the content (text) of different HTML elements together, names of the templates in translation strings in turn preserves better the text context for translators. +Be assured that you will be able to translate the content of a template (text which substitutes the template) too, but in another translation string. + +Let a text of the first numbered indent from the verification modal dialog (see fig. 6 below) which can be opened from a download page of the website serve us as an example: + +`Download the checksum file and signature into the same directory as the image you downloaded.` + +.Example of curly brackets translation in fedora-website-3.0 - original +image::Website_translation_curlybrackets_example_en.png[] + +This sentence is a combination of an ordinary text and two web links - _checksum file_ and _signature_. For the purpose of its correct translation, you are supposed to translate three translation strings. + +.string 1 +.... +Download the {checksum_file} and {signature} into the same directory as the image you downloaded. +.... + +In this string you translate averything except `{checksum_file}` and `{signature}`, which should be retained unchanged (as these 'words' are actually the names of templates). +They can be placed anywhere in your translation sentence, even their order of appereance, if appropriate, can be exchanged (`{signature}` might come first, `{checksum_file}` second). + +.string 2 and 3 +---- +cheksum file +signature +---- + +How you translate these two strings, they will appear exactly in the sentence after the website is built. +The following table shows an example of translation of the three strings to the Czech language: + +.Example comparison of string translations +[cols="1,3,3,3"] +|=== +| |English (original) |Czech (translated) |String key + +|string 1 +|Download the {checksum_file} and {signature} into the same directory as the image you downloaded. +|Stáhněte si {checksum_file} a {signature} do stejného adresáře, kam jste stáhli obraz. +|download_the_checksum_and_signature + +|string 2 +|checksum file +|soubor kontrolního součtu +|checksum file + +|string 3 +|signature +|podpis +|signature +|=== + +NOTE: Keys of both string 2 and 3 - `checksum file` and `signature` - correspond with the templates' names. + +Strings 2 and 3 substitute the templates `{checksum_file}` and `{signature}` in the string 1. So these three strings will be combined together into the resulting sentence. And the translated version works the same, as can be seen on the below image. + +.Example of curly brackets translation in fedora-website-3.0 - translated +image::Website_translation_curlybrackets_example_cs.png[] + +If templates and the text interpolation were not used, it would be needed to translate five translation strings to build the sentence: + +---- +1. Download the +2. checksum file +3. and +4. signature +5. into the same directory as the image you downloaded. +---- + +Imagine the strings in Weblate were not placed any near each other, then the text context for successful translation would be very limited, if not lost completely. + +CAUTION: If you attempted to translate directly the template names (curly brackets) in string 1, the template substitution and consequently text/translation interpolation on the website would be broken.