From 7edac26539ee217d6c661c4789e44f953dda25d3 Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Sun, 2 Mar 2025 10:58:00 +0100 Subject: [PATCH] feat(l10n): Improve translation guidelines Signed-off-by: Joas Schilling --- developer_manual/basics/front-end/l10n.rst | 134 +++++++++++++-------- 1 file changed, 86 insertions(+), 48 deletions(-) diff --git a/developer_manual/basics/front-end/l10n.rst b/developer_manual/basics/front-end/l10n.rst index bc37cdc67..63503b6cc 100644 --- a/developer_manual/basics/front-end/l10n.rst +++ b/developer_manual/basics/front-end/l10n.rst @@ -7,8 +7,8 @@ Translation Nextcloud provides mechanisms for internationalization (make an application translatable) and localization (add translations for specific languages). This section provides detailed instructions for both aspects. In order to make your app translatable (internationalization), you should use Nextcloud's methods for translating strings. They are available for both the server-side (PHP, Templates) as well as for the client-side (JavaScript). -PHP ---- +PHP Backend +----------- If localized strings are used in the backend code, simply inject the ``\OCP\IL10N`` class into your service via type hinting it in the constructor. You will automatically get the language object containing the translations of your app: @@ -16,18 +16,10 @@ If localized strings are used in the backend code, simply inject the ``\OCP\IL10 .. code-block:: php l = $l; + public function __construct( + private \OCP\IL10N $l, + ) { } … @@ -38,13 +30,12 @@ Strings can then be translated in the following way: .. code-block:: php l->getLanguageCode(); } @@ -61,14 +52,17 @@ Strings can then be translated in the following way: public function getAuthors($count, $city) { // Translation with plural return $this->l->n( - '%n author is currently in the city %1$s', // singular string - '%n authors are currently in the city %1$s', // plural string + '%n author is currently in the city %1$s', // singular string + '%n authors are currently in the city %1$s', // plural string $count, // number to decide which plural to use [$city] // further parameters are possible ); } } +FIXME +----- + Correct plurals ^^^^^^^^^^^^^^^ @@ -97,15 +91,10 @@ the ``force_language`` and ``default_language`` configuration options to conside .. code-block:: php l10nFactory = $l10nFactory; + public function __construct( + private \OCP\L10N\IFactory $l10nFactory, + ) { } public function send(IUser $user): void { @@ -116,25 +105,28 @@ the ``force_language`` and ``default_language`` configuration options to conside } -Templates ---------- +PHP Templates +------------- -In every template the global variable **$l** can be used to translate the strings using its methods **t()** and **n()**: +In every template the global variable ``$l`` can be used to translate the strings using its methods ``t()`` and ``n()``: .. code-block:: php -
t('Showing %$1s files', $_['count'])); ?>
- + // Simple text string -For the right date format use ``l('date', time()));?>``. + // Text with a placeholder +
t('Show files of %1$s', [$user])); ?>
+ // Date string + l('date', time())); ?> +JavaScript / Typescript / Vue +----------------------------- -JavaScript ----------- - -There are global functions **t()** and **n()** available for translating strings in javascript code. They differ a bit in terms of usage compared to php: +There are global functions ``t()`` and ``n()`` available for translating strings in javascript code. +If your app is build, you can import the translation functions from the `@nextcloud/l10n package `_. +They differ a bit in terms of usage compared to php: * First argument is the appId e.g. ``'myapp'`` * Placeholders (apart from the count in plurals) use single-mustache brackets with meaning-full descriptors. @@ -147,11 +139,57 @@ There are global functions **t()** and **n()** available for translating strings n('myapp', 'Import %n calendar into {collection}', 'Import %n calendars into {collection}', selectionLength, {collection: 'Nextcloud'}); +Guidelines +---------- -Important notes ---------------- +Please also look through the following hints to improve your strings and make them better translatable by the community +and therefore improving the experience for non-english users. -Please also look through the following steps to improve your strings and make them better translatable by others +.. list-table:: + :header-rows: 1 + + * - Bad + - Good + - Description + * - ``´`` or ``’`` + - ``'`` + - Use ascii single quote + * - ``Loading...`` + - ``Loading …`` + - | Use unicode triple-dot character. + | Add a space before the triple-dot when trimming a sentence instead of a word. + * - Don't + - Do not + - Using the spelled out version is easier to understand and makes translating easier. + * - Won't + - Will not + - Using the spelled out version is easier to understand and makes translating easier. + * - Can not + - Cannot + - Using the combined version is easier to understand and makes translating easier. + * - id + - ID + - Full uppercase for shortcutting "identifier" + * - Users + - Accounts / People + - Use **accounts** when you refer to a profile/entity. Use **people** when referring to humans. + * - Admin / Administrator + - Administration + - | Refer to administration as a non-human organizational entity + | instead of a single or multiple persons. + * - Headline + - Headline: + - Include colons ``:`` in the translations as some languages add a space before the colon. + * - | " Leading space" + | "Trailing space " + - | "No leading space" + | "No trailing space" + - | Leading or trailing spaces mostly indicate that strings are concatenated. + | For translators it is often helpful to have all the content in a single translation, + | as order and references between words and sentences might get lost otherwise. + * - "Error:" $error + - "Error: %s" + - Instead of concatenating errors or part messages, make them a proper placeholder Improving your translations ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -166,10 +204,10 @@ Bad example: Translators will translate: -* Select file from -* local filesystem -* ' or ' -* cloud +* ``Select file from`` +* ``local filesystem`` +* ``or`` (with leading and trailing whitespace) +* ``cloud`` Translating these individual strings results in ``local filesystem`` and ``cloud`` losing case. The two white spaces surrounding ``or`` will get lost while translating as well. For languages that have a different grammatical order it prevents the translators from reordering the sentence components. @@ -196,7 +234,7 @@ This allows translators to have the cloudlink before the browselink in case the .. _Hints: Provide context hints for translators -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------- In case some translation strings may be translated wrongly because they have multiple meanings, you can add hints which will be shown in the Transifex web-interface: @@ -213,7 +251,7 @@ In case some translation strings may be translated wrongly because they have mul -**Javascript** +**Javascript / Typescript** .. code-block:: javascript @@ -261,8 +299,8 @@ Nextcloud's translation system is powered by `Transifex