From 48f2b47c34bb3c2b738c876237767453ae990cb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Allan=20Nordh=C3=B8y?= Date: Fri, 19 May 2023 12:19:31 +0000 Subject: [PATCH 1/4] docs: Fetching translation from Weblate reworked --- docs/devel/integration.rst | 105 +++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 52 deletions(-) diff --git a/docs/devel/integration.rst b/docs/devel/integration.rst index 5848eef88312..7c84b5bda432 100644 --- a/docs/devel/integration.rst +++ b/docs/devel/integration.rst @@ -3,15 +3,16 @@ Integrating with Weblate .. include:: /snippets/basics.rst -Importing localization project into Weblate -+++++++++++++++++++++++++++++++++++++++++++ +Importing localization projects into Weblate +++++++++++++++++++++++++++++++++++++++++++++ -Weblate has been developed with VCS integration in mind as it’s core feature, so the easiest way is -to grant Weblate the access to your repository. -The import process will guide you through configuring your translations into components. +The most automated of maintaining integration with a remote +version-control repository is to grant Weblate access to it. +The import process guides you through configuring and splitting up your +translation effort into Weblate components. -Alternatively, you can use Weblate to set up a local repository containing -all the translations without integration. +Alternatively, you can use Weblate without any integration, where +a local repository contains all translations. .. seealso:: @@ -22,19 +23,19 @@ Fetching updated translations from Weblate ++++++++++++++++++++++++++++++++++++++++++ Weblate stores updated strings in a database and commits them to a local -version control repository. You can add Weblate repository (when -:ref:`git-exporter` is turned on) as additional remote and fetch translations -update from it. +version-control repository. You can add a Weblate repository (when +:ref:`git-exporter` is turned on) as an additional remote repository +and fetch translations updates from it. -Prior to this, you might want to commit any pending -changes (see :ref:`lazy-commit`). You can do so in the user interface -(in the :guilabel:`Repository maintenance`) or from the command-line using :ref:`wlc`. +Prior to this, you might want to commit any pending local +changes made in Weblate (see :ref:`lazy-commit`). This can be done from the user interface +(in the :guilabel:`Repository maintenance`), or from the command-line using :ref:`wlc`. Pushing changes can be automated if you grant Weblate push access to your repository and configure :ref:`component-push` in the :ref:`component`, see :ref:`push-changes`. -Alternatively, you can use :doc:`/api` to update translations -to match their latest version. +Alternatively, use :doc:`/api` to update translations +so that they match the latest version from upstream in your remote VCS repository. .. seealso:: @@ -45,15 +46,16 @@ to match their latest version. Fetching remote changes into Weblate ++++++++++++++++++++++++++++++++++++ -To fetch the strings newly updated in your repository into Weblate, just let it pull from the upstream -repository. This can be achieved in the user interface (in the :guilabel:`Repository -maintenance`), or from the command-line using :ref:`wlc`. +To fetch any strings recently updated in your remote VCS repository into Weblate, +allow Weblate pull from the upstream repository. +This can be achieved in the user interface (in the :guilabel:`Repository maintenance`), +or from the command-line using :ref:`wlc`. This can be automated by setting a webhook in your repository to trigger -Weblate whenever there is a new commit, see :ref:`update-vcs` for more details. +Weblate whenever there is a new commit. See :ref:`update-vcs` for more details. -If you’re not using a VCS integration, you can use UI or :doc:`/api` to update -translations to match your code base. +If not using VCS integration, you can use the UI or :doc:`/api` to update +the translations so that they match your codebase. .. seealso:: @@ -65,41 +67,41 @@ translations to match your code base. Adding new strings ++++++++++++++++++ -In case your translation files are stored in a VCS together with the code, +If your translation files are stored in a remote VCS together with the code, you most likely have an existing workflow for developers to introduce new strings. Any way of adding strings will be picked up, but consider using :ref:`source-quality-gateway` to avoid introducing errors. -When the translation files are separate from the code, there are following ways to introduce -new strings into Weblate. +When translation files are separated from the code, there following ways can +introduce new strings into Weblate. * Manually, using :guilabel:`Add new translation string` from :guilabel:`Tools` menu in the source language. -* Programmatically, using API :http:post:`/api/translations/(string:project)/(string:component)/(string:language)/units/`. +* Programmatically, using the API :http:post:`/api/translations/(string:project)/(string:component)/(string:language)/units/`. * By uploading source file as :guilabel:`Replace existing translation file` - (this overwrites existing strings, so please make sure the file includes both + (this overwrites existing strings, so please ensure the file includes both old and new strings) or :guilabel:`Add new strings`, see :ref:`upload-method`. .. note:: - Availability of adding strings in Weblate depends on :ref:`component-manage_units`. + The ability to add strings in Weblate requires :ref:`component-manage_units`. .. _updating-target-files: -Updating target language files +Updating target-language files ++++++++++++++++++++++++++++++ For monolingual files (see :ref:`formats`) Weblate might add new translation -strings not present in the :ref:`component-template`, and not in actual -translations. It does not however perform any automatic cleanup of stale -strings as that might have unexpected outcomes. If you want to do this, please -install :ref:`addon-weblate.cleanup.generic` add-on which will handle the +strings not present in the :ref:`component-template`, or other translations. +It does not however perform any automatic cleanup of stale strings, as that +might have unexpected results. If you still want to do this, please install +the :ref:`addon-weblate.cleanup.generic` add-on, which handles cleanup according to your requirements. -Weblate also will not try to update bilingual files in any way, so if you need -:file:`po` files being updated from :file:`pot`, you need to do it yourself -using :guilabel:`Update source strings` :ref:`upload-method` or using -:ref:`addon-weblate.gettext.msgmerge` add-on. +Weblate will also not try to update bilingual files in any way, so if you need +:file:`po` files to be updated from :file:`pot`, do it yourself by +using :guilabel:`Update source strings` :ref:`upload-method`, or by using +the :ref:`addon-weblate.gettext.msgmerge` add-on. .. seealso:: @@ -119,21 +121,21 @@ You can add new strings in Weblate with :ref:`component-manage_units` turned on, but it is usually better to introduce new strigs together with the code changes that introduced them. -Monolingual formats need addition of the new string to -:ref:`component-template`. This is typically done by the developers during -developing the code. You might want to introduce review of those strings using +Monolingual formats need to be configured so that new strings are added to +:ref:`component-template`. This is typically done by developers as they +develop the code. You might want to introduce review of those strings using :ref:`source-quality-gateway`. Bilingual formats typically extract strings from the source code using some -tooling. Follow your localization framework documentation for instructions how -to do that. Once the strings are extracted, there might be an additional step +tooling. Follow your localization-framework documentation for instructions on +how to do that. Once strings are extracted, an additional step might be needed to update existing translations, see :ref:`updating-target-files`. .. hint:: - You might want to integrate this into your contrinuous integration pipelines - to make new strings automatically appear for translation. Such pipeline - should also cover :ref:`avoid-merge-conflicts`. + Integrate this into your contrinuous-integration pipelines + if you want new strings to appear automatically for translation. + Such a pipeline should also cover :ref:`avoid-merge-conflicts`. .. seealso:: @@ -143,18 +145,17 @@ needed to update existing translations, see :ref:`updating-target-files`. .. _manage-vcs: -Managing version control repository -+++++++++++++++++++++++++++++++++++ +Managing the local VCS repository ++++++++++++++++++++++++++++++++++ -Weblate stores all translation the version control repository. It can be either -connected to upstream one, or it can be only internal. The :guilabel:`Repository -maintenance` lets you manipulate with the repository. +Weblate stores all translations a version control repository of its own. +It can either be connected to a remote one, or it can remain internal only. +The :guilabel:`Repository maintenance` allows manipulating the repository. .. hint:: - With :doc:`/admin/continuous` the repository is automatically pushed - whenever there are changes and there is usually no need to manually - manipulate with it. + With :doc:`/admin/continuous` any changes are auto-pushed from the + repository, and there is usually no need to manually manipulate it. .. image:: /screenshots/component-repository.png From 7ca0e5bf61761e82f32464965286e173ae5b4419 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Allan=20Nordh=C3=B8y?= Date: Fri, 19 May 2023 12:28:52 +0000 Subject: [PATCH 2/4] Small typos --- docs/devel/integration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/devel/integration.rst b/docs/devel/integration.rst index 7c84b5bda432..89becbcb1415 100644 --- a/docs/devel/integration.rst +++ b/docs/devel/integration.rst @@ -25,7 +25,7 @@ Fetching updated translations from Weblate Weblate stores updated strings in a database and commits them to a local version-control repository. You can add a Weblate repository (when :ref:`git-exporter` is turned on) as an additional remote repository -and fetch translations updates from it. +and fetch translation updates from it. Prior to this, you might want to commit any pending local changes made in Weblate (see :ref:`lazy-commit`). This can be done from the user interface @@ -118,7 +118,7 @@ Introducing new strings +++++++++++++++++++++++ You can add new strings in Weblate with :ref:`component-manage_units` turned -on, but it is usually better to introduce new strigs together with the code +on, but it is usually better to introduce new strings together with the code changes that introduced them. Monolingual formats need to be configured so that new strings are added to From 3aeb8434438eee5cc7f82b8bf49348dc13518960 Mon Sep 17 00:00:00 2001 From: Benjamin Alan Jamie Date: Fri, 28 Jun 2024 11:43:01 +0200 Subject: [PATCH 3/4] polishing and sense correction Rewriting, so it describes the actual functioning. --- docs/devel/integration.rst | 45 +++++++++++++++++++++----------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/devel/integration.rst b/docs/devel/integration.rst index 00cc12808e71..0f089a0e02f6 100644 --- a/docs/devel/integration.rst +++ b/docs/devel/integration.rst @@ -3,16 +3,16 @@ Integrating with Weblate .. include:: /snippets/basics.rst -Importing localization projects into Weblate -++++++++++++++++++++++++++++++++++++++++++++ +Importing a localization project into Weblate ++++++++++++++++++++++++++++++++++++++++++++++ -The most automated of maintaining integration with a remote -version-control repository is to grant Weblate access to it. -The import process guides you through configuring and splitting up your -translation effort into Weblate components. +Weblate has been developed with VCS integration in mind as it’s core feature, +so the easiest way is to grant Weblate the access to your repository. +The import process will guide you through configuring your translations +into Weblate components. -Alternatively, you can use Weblate without any integration, where -a local repository contains all translations. +Alternatively, you can let Weblate set up a local-only repository +containing all the translations without integration. .. seealso:: @@ -35,7 +35,7 @@ Pushing changes can be automated if you grant Weblate push access to your reposi configure :ref:`component-push` in the :ref:`component`, see :ref:`push-changes`. Alternatively, use :doc:`/api` to update translations -so that they match the latest version from upstream in your remote VCS repository. +so that they match the latest version from the upstream in your remote VCS repository. .. seealso:: @@ -47,7 +47,7 @@ Fetching remote changes into Weblate ++++++++++++++++++++++++++++++++++++ To fetch any strings recently updated in your remote VCS repository into Weblate, -allow Weblate pull from the upstream repository. +allow Weblate to pull from the upstream repository. This can be achieved in the user interface (in the :guilabel:`Repository maintenance`), or from the command-line using :ref:`wlc`. @@ -91,18 +91,22 @@ introduce new strings into Weblate. Updating target-language files ++++++++++++++++++++++++++++++ -For monolingual files (see :ref:`formats`) Weblate might add new translation -strings not present in the :ref:`component-template`, or other translations. +For monolingual files (see :ref:`formats`), Weblate might add new translation +strings present in the :ref:`component-template`, and not in actual translations. It does not however perform any automatic cleanup of stale strings, as that might have unexpected results. If you still want to do this, please install the :ref:`addon-weblate.cleanup.generic` add-on, which handles cleanup according to your requirements. -Weblate will also not try to update bilingual files in any way, so if you need -:file:`po` files to be updated from :file:`pot`, do it yourself by +Weblate will also not try to update bilingual files when the source changes, +so if you need :file:`po` files to be updated from :file:`pot`, do it yourself by using :guilabel:`Update source strings` :ref:`upload-method`, or by using the :ref:`addon-weblate.gettext.msgmerge` add-on. +.. hint:: + + Source string extraction tools, such as :program:`xgettext` or :program:`lupdate`, need to be executed outside of Weblate. + .. seealso:: :ref:`processing`, @@ -123,7 +127,7 @@ changes that introduced them. Monolingual formats need to be configured so that new strings are added to :ref:`component-template`. This is typically done by developers as they -develop the code. You might want to introduce review of those strings using +write the code. You might want to use a review proccess of those strings using :ref:`source-quality-gateway`. Bilingual formats typically extract strings from the source code using some @@ -153,14 +157,15 @@ existing translations, see :ref:`updating-target-files`. Managing the local VCS repository +++++++++++++++++++++++++++++++++ -Weblate stores all translations a version control repository of its own. -It can either be connected to a remote one, or it can remain internal only. -The :guilabel:`Repository maintenance` allows manipulating the repository. +Weblate stores all translations in its underlying version control repository. +It is suggested to be connected to a remote one, but internal-only setup is +also possible. The :guilabel:`Repository maintenance` allows +controlling this repository. .. hint:: - With :doc:`/admin/continuous` any changes are auto-pushed from the - repository, and there is usually no need to manually manipulate it. + With :doc:`/admin/continuous`, any changes are automatically pushed from the + repository, so there is usually no need to manually manage it manually. .. image:: /screenshots/component-repository.webp From cb04b6927d7d4edcf95022f064e772d1c317bde2 Mon Sep 17 00:00:00 2001 From: Benjamin Alan Jamie Date: Fri, 28 Jun 2024 11:46:40 +0200 Subject: [PATCH 4/4] spelling correction --- docs/devel/integration.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/devel/integration.rst b/docs/devel/integration.rst index 3b6a5fd3b845..df7496726d4b 100644 --- a/docs/devel/integration.rst +++ b/docs/devel/integration.rst @@ -128,8 +128,8 @@ on, but it is usually better to introduce new strings together with the code changes that introduced them. Monolingual formats need to be configured so that new strings are added to -:ref:`component-template`. This is typically done by developers as they -write the code. You might want to use a review proccess of those strings using +:ref:`component-template`. This is typically done by developers, as they +write the code. You might want to use a review process of those strings using :ref:`source-quality-gateway`. Bilingual formats typically extract strings from the source code using some