From 513f4c30c1644bbc24eaa28a9c6391d488995150 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Imobach=20Gonz=C3=A1lez=20Sosa?= Date: Tue, 24 Sep 2024 12:00:06 +0100 Subject: [PATCH] doc(website): partially adapt to SUSE style guide --- website/docs/devel/i18n.md | 76 ++++++++++++++++----------------- website/docs/devel/packaging.md | 8 ++-- website/docs/devel/yupdate.md | 21 ++++----- website/docs/index.md | 2 +- website/docs/user/autoyast.md | 2 +- 5 files changed, 55 insertions(+), 54 deletions(-) diff --git a/website/docs/devel/i18n.md b/website/docs/devel/i18n.md index 4fee636bc9..d4cb84e7f7 100644 --- a/website/docs/devel/i18n.md +++ b/website/docs/devel/i18n.md @@ -10,18 +10,18 @@ languages and locales in software. This page describes how is that handled in Ag Each component need to solve this problem separately, see more details for each part in the details below. -## Using Translations +## Using translations Users have two ways how to change the used language in the Agama interface. -### Language Selector +### Language selector The sidebar of the web UI contains a component that allows to change the language. It was introduced in Agama 5 and it is the recommended way. The list of supported languages is read from the [languages.json](https://github.com/openSUSE/agama/blob/master/web/src/languages.json) file. Check -the [The Web Frontend](#the-web-frontend) for further details. +the [The web front-end](#the-web-front-end) for further details. -### URL Query Parameter +### URL query parameter When using a remote installation it is possible to set the used language via an URL query parameter. This is an expert option. @@ -42,7 +42,7 @@ beginning. For translation process Agama uses [Weblate](https://weblate.org/) tool running at the [openSUSE](https://l10n.opensuse.org/) instance. -## The Workflow +## The workflow The basic translation workflow looks like this: @@ -58,7 +58,7 @@ The basic translation workflow looks like this: 6. The translations in the PO files are regularly copied to the main repository using pull requests 7. The PO files are processed during build so the translations can be used later at runtime -## Staging Translation Repository +## Staging translation repository The special [agama-weblate](https://github.com/openSUSE/agama-weblate) repository works like a buffer between the Agama sources and the Weblate tool. @@ -77,7 +77,7 @@ The content between the main [agama](https://github.com/openSUSE/agama) and the [agama-weblate](https://github.com/openSUSE/agama-weblate) GitHub repositories is synchronized automatically using the GitHub Actions. -### Uploading Translatable Texts +### Uploading translatable texts Collecting and uploading the translatable texts is done by the [weblate-update-pot.yml](https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-update-pot.yml) @@ -94,7 +94,7 @@ action detail and use the "Run workflow" option at the top of the page. The code compares the old POT file with the new one and if there is no change besides the timestamps in the file it is not uploaded to `agama-weblate`. -### Downloading Updated Translations +### Downloading updated translations The translations from the `agama-weblate` repository are merged back by the [weblate-merge-po.yml](https://github.com/openSUSE/agama/blob/master/.github/workflows/weblate-merge-po.yml) @@ -107,35 +107,35 @@ GitHub action. If there are no changes besides the timestamps in the PO files the pull request is not created. -## Weblate Configuration +## Weblate configuration The [Agama Weblate](https://l10n.opensuse.org/projects/agama/) project defines a separate -translation component for each Agama part (the web frontend, the D-Bus backend and the command line -interface). +translation component for each Agama part (the web front-end, the D-Bus back-end and the command +line interface). For reading the translations it uses the [agama-weblate](https://github.com/openSUSE/agama-weblate) GitHub repository, but for the source code locations it uses the original [agama](https://github.com/openSUSE/agama) repository. That means after clicking the source location link in the Weblate you will see the correct source location in the other repository. -### Plugins +### Plug-ins The Weblate components use the [msgmerge](https://docs.weblate.org/en/weblate-4.9.1/admin/addons.html#addon-weblate-gettext-msgmerge) -plugin which automatically updates all PO files to match the POT file. That means after adding or +plug-in which automatically updates all PO files to match the POT file. That means after adding or updating any translatable text the changes are automatically applied to all existing PO files and translators can translate the new or updated texts immediately. -## Technical Details +## Technical details This part describes technical and implementation details. It also describes the translation process for developers. -### The Web Frontend +### The web front-end -Most of the translatable texts which can user see in Agama are defined in the web frontend. However, -the web frontend can display some translated texts coming from the backend part so it is important -to set the same language in both parts and make sure the translations are available there. +Most of the translatable texts which can user see in Agama are defined in the web front-end. +However, the web front-end can display some translated texts coming from the back-end part so it is +important to set the same language in both parts and make sure the translations are available there. The list of supported languages is read from the [languages.json](https://github.com/openSUSE/agama/blob/master/web/src/languages.json). Such a list @@ -160,7 +160,7 @@ If you need to manually update the `languages.json` file, run: web/share/update-languages.py > web/src/languages.json ``` -### Marking Texts for Translation +### Marking texts for translation The texts are marked for translation using the usual functions like `_()`, `n_()` and others. It is similar to the GNU gettext style. @@ -213,7 +213,7 @@ If you need to insert some values into the text you should use the [formatting function](#formatting-texts). It is recommended to use [translator comments](#translators-comments) for short or ambiguous texts. -#### Plural Form +#### Plural form If the translated text contains a number or quantity it is good to use a plural form so the translated texts looks naturally. @@ -233,7 +233,7 @@ specific number. See more details about the [plural forms](https://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html) in the GNU gettext documentation. -#### Translating Constants +#### Translating constants The top-level constants are evaluated too early, at that time the translations are not available yet and the language is not set. @@ -253,7 +253,7 @@ export default function Foo() { ``` -#### Formatting Texts +#### Formatting texts For formatting complex texts use the C-like `sprintf()` function. @@ -309,7 +309,7 @@ sprintf(_("Service is %s enabled"), msgNot); enabled ? _("Service is enabled") : _("Service is disabled"); ``` -#### TRANSLATORS Comments +#### TRANSLATORS comments You can use a special `TRANSLATORS` keyword in the comment preceding the text marked for translation. All comments after the keyword are included in the translations file, this should help @@ -362,7 +362,7 @@ The translators can change the order of the arguments if needed using additional arguments. For example to change the order of the arguments in `"Foo %s %s"` they can translate it as `"Bar %2$s %1$s"`. -### Missing Translations +### Missing translations Here are some code examples which might look correct at the first sight. They even work, no crash. But there are still translation problems with them. @@ -376,13 +376,13 @@ user)`). In both cases the strings will not be extracted to the POT file. -### ESLint Plugin +### ESLint plug-in -There is special ESLint plugin +There is special ESLint plug-in [eslint-plugin-agama-i18n](https://github.com/openSUSE/eslint-plugin-agama-i18n) which ensures that a string literal is passed to the translation functions. See more details there. -### Testing Language +### Testing language The Agama web interface supports special testing `xx` language. That language needs to be selected manually by adding the `?lang=xx` query string to the server URL. With this setting the `_()` and @@ -390,13 +390,13 @@ manually by adding the `?lang=xx` query string to the server URL. With this sett This can be used for testing to find out the texts which are not marked for translation. If a text is not replaced by the `x` symbols then either it is not marked for translation or it comes from the -backend and it should be translated by the backend. +back-end and it should be translated by the back-end. However, this is not perfect. It will replace also the texts mentioned in the [missing translations](#missing-translations) section above but in reality the there would be no translations available for them. -### Building POT File +### Building the POT file The translatable strings are extracted from the source files by using the standard `xgettext` tool. There is a helper script [build_pot](https://github.com/openSUSE/agama/blob/master/web/build_pot) @@ -404,7 +404,7 @@ which defines the needed parameters for the `xgettext` tool. To build the POT file locally just run the script, it will save the output to the `agama.pot` file. -### Loading Web UI Translations +### Loading web UI translations The translations are loaded by the `` HTML code in the [index.html](https://github.com/openSUSE/agama/blob/master/web/src/index.html) file. But there is no @@ -413,7 +413,7 @@ such file in Agama but one `po..js` file per language, like `po.cs.js`. The trick is that Agama's web server checks the `agamaLang` cookie sent in the HTTP request header and returns the content from the respective file. -### Development Server +### Development server Because Agama serves the `po.js` file a bit differently as described in the [](#loading-web-ui-translations) section above we need to implement this logic also in the @@ -426,7 +426,7 @@ uses redirection because the built translation files are only available in the w the result is the same, the browser gets a different content according to the currently configured language. -### Backend Locale +### Back-end locale The Agama server exposes a `uiLocale` configuration option via the `/api/l10n/locales/config` endpoint which defines the locale used by all the services. @@ -434,7 +434,7 @@ endpoint which defines the locale used by all the services. The `uiLocale` property is a single global value shared by all connected clients. That means it is possible to use only one language for all clients, if more users connect to the server and uses a different UI language then there will be race conditions and the other users might see the texts -coming from the backend in another language than expected. +coming from the back-end in another language than expected. This is a known limitation, we expect that only one user at a time will access the Agama installer or if multiple users use the same server we expect that they will be from the same team or company @@ -448,9 +448,9 @@ sudo busctl --address unix:path=/run/agama/bus get-property org.opensuse.Agama1 /org/opensuse/Agama1/Locale org.opensuse.Agama1.Locale UILocale ``` -#### Backend Translations +#### Back-end translations -The backend might return texts from external components like `libstorage-ng`. Make sure the +The back-end might return texts from external components like `libstorage-ng`. Make sure the translations for those components are also available for Agama, e.g. the `libstorage-ng` translations are stored in the `libstorage-ng-lang` package or the YaST translations are stored in `yast2-trans-` packages. @@ -461,8 +461,8 @@ Here are some hints what to do when some untranslated text appears in the Agama 1. Check that the text is marked for translation, for a quick verification you might try setting the [testing language](#testing-language). -2. If the text comes from backend or the other parts check that the appropriate [language - package](#backend-translations) is installed. +2. If the text comes from back-end or the other parts check that the appropriate [language + package](#back-end-translations) is installed. 3. The text should be [extracted into the POT file](#building-pot-file) 4. The [agama.pot](https://github.com/openSUSE/agama-weblate/blob/master/web/agama.pot) in the `agama-weblate` repository is up to date, if not then run the [Weblate Update @@ -483,4 +483,4 @@ Here are some hints what to do when some untranslated text appears in the Agama 10. Check the current language used in the browser, run `agama.language` command in the development tools console, check the `agamaLang` cookie value (run `document.cookie` command in the console). -11. Check the language used by the [Backend Locale](#backend-locale). +11. Check the language used by the [Back-end locale](#back-end-locale). diff --git a/website/docs/devel/packaging.md b/website/docs/devel/packaging.md index 493d49ce36..7cdb27ce6e 100644 --- a/website/docs/devel/packaging.md +++ b/website/docs/devel/packaging.md @@ -15,14 +15,14 @@ While the Ruby-based one (`rubygem-agama-yast`) is built as any other YaST packa (`agama`), the CLI (`agama-cli`), and the web UI (`agama-web-ui`) rely on [OBS source services](https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.source_service.html). -## Versioning Policy +## Versioning policy We have decided to follow a single number schema: 1, 2, 3, etc. However, if we need to release a hot-fix, we might use a dotted version (e.g., 2.1). Moreover, all the components share the same version number. Releasing a new version implies that all of them get the new number, no matter if they contain changes or not. -## Bumping the Version +## Bumping the version In order to release a new version, we need to: @@ -47,7 +47,7 @@ After creating the tag on the server the GitHub Actions will publish the package [systemsmanagement:Agama:Devel](https://build.opensuse.org/project/show/systemsmanagement:Agama:Devel) project and create submit requests to openSUSE Factory. -## Building the Packages +## Building the packages The packages are updated automatically using the GitHub actions. Here are details for manual update. @@ -104,7 +104,7 @@ the latest commit respect such a tag. (e.g. `2.1+42`). You can read more about the overall approach of this package in the following article: [Git work flows in the upcoming 2.7 release](https://openbuildservice.org/2016/04/08/new_git_in_27/). -### The Live ISO +### The live ISO The ISO for openSUSE products is built in the [systemsmanagement:Agama:Devel/agama-installer-openSUSE](https://build.opensuse.org/package/show/systemsmanagement:Agama:Devel/agama-installer-openSUSE) diff --git a/website/docs/devel/yupdate.md b/website/docs/devel/yupdate.md index 38ac6975f3..b59d412fc0 100644 --- a/website/docs/devel/yupdate.md +++ b/website/docs/devel/yupdate.md @@ -27,7 +27,7 @@ yupdate patch openSUSE/agama master You can replace the `master` branch with any branch containing a fix or a new feature. -## Patching from a Local Git Checkout +## Patching from a local Git checkout First you need to run the `rake server` command in your Agama Git checkout. @@ -56,10 +56,11 @@ You can modify the update process with these environment variables: - `NODE_ENV=development` - The web front-end will be built in the development mode. The files will not be minimized and additional `*.map` files will be generated. This helps with debugging in the browser, you can get the locations in the original source files. -- `YUPDATE_SKIP_FRONTEND=1` - Skip updating the web frontend. Use this option when you use the - webpack development server for running the web frontend. In that case updating the web frontend does - not make sense because it is running in a different server. This saves some time and disk/RAM space. -- `YUPDATE_SKIP_BACKEND=1` - Skip updating the D-Bus service backend. This is similar to the +- `YUPDATE_SKIP_FRONTEND=1` - Skip updating the web front-end. Use this option when you use the + webpack development server for running the web front-end. In that case updating the web front-end + does not make sense because it is running in a different server. This saves some time and disk/RAM + space. +- `YUPDATE_SKIP_BACKEND=1` - Skip updating the D-Bus service back-end. This is similar to the previous option, use it when you do want to keep the D-Bus service unchanged. ## Notes @@ -74,12 +75,12 @@ system becomes completely frozen and might not respond to any input event. Currently the minimum for a safe operation is around 4GB RAM. If you use the `NPM_CACHE=1` option then recommended minimum is around 5GB. -## Activating the Changes +## Activating the changes After patching the files the DBus service is restarted if any related file has been changed. That means the configured settings will be lost. -To activate the changes in the web frontend you need to reload the page in the browser. +To activate the changes in the web front-end you need to reload the page in the browser. :::warning _In the Firefox browser you need to use the `Ctrl+F5` combination for reloading the page, @@ -90,7 +91,7 @@ update on the server!_ In some special cases you might need to do some additional actions manually, the update script might not handle all corner cases. -## Implementation Details +## Implementation details The support is implemented in the main [Rakefile](https://github.com/openSUSE/agama/blob/master/Rakefile) and in the @@ -98,5 +99,5 @@ The support is implemented in the main [.yupdate.post](https://github.com/openSUSE/agama/blob/master/.yupdate.post) hook scripts. - The `.yupdate.pre` script prepares the system for compiling and installing new Agama files. -- The `Rakefile` code builds and installs both backend and frontend parts. -- The `.yupdate.pre` script activates the changes, it restarts the backend if needed. +- The `Rakefile` code builds and installs both back-end and front-end parts. +- The `.yupdate.pre` script activates the changes, it restarts the back-end if needed. diff --git a/website/docs/index.md b/website/docs/index.md index 368a41c703..054d46f030 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# About +# Agama's documentation This section covers a wide range of Agama-related topics. To make it easy to find the information you are looking for, the documentation is organized in two different parts, depending on your diff --git a/website/docs/user/autoyast.md b/website/docs/user/autoyast.md index 061eaaa4ee..fc43495b28 100644 --- a/website/docs/user/autoyast.md +++ b/website/docs/user/autoyast.md @@ -1,4 +1,4 @@ -# AutoYaST Support +# AutoYaST support Agama offers a mechanism to perform [unattended installations](./unattended). However, we would like AutoYaST users to be able to use their profiles in Agama. This document describes how