From 10235a606c10c36ece138bac20e5e07897b27cd1 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:47:17 +0900 Subject: [PATCH 1/9] docs: move / after folder names --- user_guide_src/source/outgoing/localization.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/user_guide_src/source/outgoing/localization.rst b/user_guide_src/source/outgoing/localization.rst index 2a1f3f5b4197..d6e4a1d1a47b 100644 --- a/user_guide_src/source/outgoing/localization.rst +++ b/user_guide_src/source/outgoing/localization.rst @@ -17,11 +17,11 @@ with different supported languages. Language strings are stored in the **app/Language** directory, with a sub-directory for each supported language:: - /app - /Language - /en + app/ + Language/ + en/ App.php - /fr + fr/ App.php .. important:: Locale detection only works for web-based requests that use the IncomingRequest class. From c7e34fbeec7b5d1a89ed906b69ca59c7a52acc1e Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:48:53 +0900 Subject: [PATCH 2/9] docs: use ** for file paths --- .../source/outgoing/localization.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/user_guide_src/source/outgoing/localization.rst b/user_guide_src/source/outgoing/localization.rst index d6e4a1d1a47b..beedb5743125 100644 --- a/user_guide_src/source/outgoing/localization.rst +++ b/user_guide_src/source/outgoing/localization.rst @@ -30,7 +30,7 @@ supported language:: Configuring the Locale ====================== -Every site will have a default language/locale they operate in. This can be set in **Config/App.php**: +Every site will have a default language/locale they operate in. This can be set in **app/Config/App.php**: .. literalinclude:: localization/001.php @@ -57,7 +57,7 @@ Should you ever need to set the locale directly you may use ``IncomingRequest::s Content Negotiation ------------------- -You can set up content negotiation to happen automatically by setting two additional settings in Config/App. +You can set up content negotiation to happen automatically by setting two additional settings in **app/Config/App.php**. The first value tells the Request class that we do want to negotiate a locale, so simply set it to true: .. literalinclude:: localization/002.php @@ -129,7 +129,7 @@ Basic Usage You can use the ``lang()`` helper function to retrieve text from any of the language files, by passing the filename and the language key as the first parameter, separated by a period (.). For example, to load the -``errorEmailMissing`` string from the ``Errors`` language file, you would do the following: +``errorEmailMissing`` string from the **Errors.php** language file, you would do the following: .. literalinclude:: localization/010.php @@ -198,8 +198,8 @@ Language Fallback ================= If you have a set of messages for a given locale, for instance -``Language/en/app.php``, you can add language variants for that locale, -each in its own folder, for instance ``Language/en-US/app.php``. +**Language/en/app.php**, you can add language variants for that locale, +each in its own folder, for instance **Language/en-US/app.php**. You only need to provide values for those messages that would be localized differently for that locale variant. Any missing message @@ -210,8 +210,8 @@ in case new messages are added to the framework and you haven't had a chance to translate them yet for your locale. So, if you are using the locale ``fr-CA``, then a localized -message will first be sought in ``Language/fr/CA``, then in -``Language/fr``, and finally in ``Language/en``. +message will first be sought in the **Language/fr-CA** directory, then in +the **Language/fr** directory, and finally in the **Language/en** directory. Message Translations ==================== @@ -219,9 +219,9 @@ Message Translations We have an "official" set of translations in their `own repository `_. -You could download that repository, and copy its ``Language`` folder -into your ``app``. The incorporated translations will be automatically -picked up because the ``App`` namespace is mapped to your ``app`` folder. +You could download that repository, and copy its **Language** folder +into your **app** folder. The incorporated translations will be automatically +picked up because the ``App`` namespace is mapped to your **app** folder. Alternately, a better practice would be to ``composer require codeigniter4/translations`` inside your project, and the translated messages will be automatically picked From f0d980f05ef8c5ad0068807fb47464418dd947e2 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:50:00 +0900 Subject: [PATCH 3/9] docs: add note for namespaces --- user_guide_src/source/outgoing/localization.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/user_guide_src/source/outgoing/localization.rst b/user_guide_src/source/outgoing/localization.rst index beedb5743125..5fa11bcce51e 100644 --- a/user_guide_src/source/outgoing/localization.rst +++ b/user_guide_src/source/outgoing/localization.rst @@ -110,6 +110,8 @@ Language Localization Creating Language Files ======================= +.. note:: The Language Files do not have namespaces. + Languages do not have any specific naming convention that are required. The file should be named logically to describe the type of content it holds. For example, let's say you want to create a file containing error messages. You might name it simply: **Errors.php**. From 743f44da67cf1aa4de8e396dce3ff31bb6900938 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:50:51 +0900 Subject: [PATCH 4/9] docs: improve description --- user_guide_src/source/outgoing/localization.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/user_guide_src/source/outgoing/localization.rst b/user_guide_src/source/outgoing/localization.rst index 5fa11bcce51e..ccec62734a08 100644 --- a/user_guide_src/source/outgoing/localization.rst +++ b/user_guide_src/source/outgoing/localization.rst @@ -89,7 +89,7 @@ file: .. literalinclude:: localization/018.php -.. note:: ``useSupportedLocalesOnly()`` can be used since v4.3.0. +.. note:: The ``useSupportedLocalesOnly()`` method can be used since v4.3.0. Retrieving the Current Locale ============================= @@ -225,6 +225,10 @@ You could download that repository, and copy its **Language** folder into your **app** folder. The incorporated translations will be automatically picked up because the ``App`` namespace is mapped to your **app** folder. -Alternately, a better practice would be to ``composer require codeigniter4/translations`` -inside your project, and the translated messages will be automatically picked +Alternately, a better practice would be to run the following command inside your +project:: + + > composer require codeigniter4/translations + +The translated messages will be automatically picked up because the translations folders get mapped appropriately. From c19a9a44f11990b1631253b66c51ea2c678325e5 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:51:20 +0900 Subject: [PATCH 5/9] docs: replace method with function --- user_guide_src/source/outgoing/localization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/outgoing/localization.rst b/user_guide_src/source/outgoing/localization.rst index ccec62734a08..9755b50b279a 100644 --- a/user_guide_src/source/outgoing/localization.rst +++ b/user_guide_src/source/outgoing/localization.rst @@ -185,7 +185,7 @@ Specifying Locale ----------------- To specify a different locale to be used when replacing parameters, you can pass the locale in as the -third parameter to the ``lang()`` method. +third parameter to the ``lang()`` function. .. literalinclude:: localization/016.php From a10c4f6f032f9531b84a72cec1f1f762df9e0697 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:51:50 +0900 Subject: [PATCH 6/9] docs: make function name linkable --- user_guide_src/source/outgoing/localization.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/outgoing/localization.rst b/user_guide_src/source/outgoing/localization.rst index 9755b50b279a..7e495adb00e5 100644 --- a/user_guide_src/source/outgoing/localization.rst +++ b/user_guide_src/source/outgoing/localization.rst @@ -129,7 +129,7 @@ It also support nested definition: Basic Usage =========== -You can use the ``lang()`` helper function to retrieve text from any of the language files, by passing the +You can use the :php:func:`lang()` helper function to retrieve text from any of the language files, by passing the filename and the language key as the first parameter, separated by a period (.). For example, to load the ``errorEmailMissing`` string from the **Errors.php** language file, you would do the following: From 8a9ed47edd56c418dfe144eebbf67ec06918ab2c Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:52:11 +0900 Subject: [PATCH 7/9] docs: change text decration --- user_guide_src/source/outgoing/localization.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/user_guide_src/source/outgoing/localization.rst b/user_guide_src/source/outgoing/localization.rst index 7e495adb00e5..2cff7700b091 100644 --- a/user_guide_src/source/outgoing/localization.rst +++ b/user_guide_src/source/outgoing/localization.rst @@ -40,9 +40,9 @@ language codes like en-US for American English, or fr-FR, for French/France. A m to this can be found on the `W3C's site `_. The system is smart enough to fall back to more generic language codes if an exact match -cannot be found. If the locale code was set to **en-US** and we only have language files set up for **en** -then those will be used since nothing exists for the more specific **en-US**. If, however, a language -directory existed at **app/Language/en-US** then that would be used first. +cannot be found. If the locale code was set to ``en-US`` and we only have language files set up for ``en`` +then those will be used since nothing exists for the more specific ``en-US``. If, however, a language +directory existed at the **app/Language/en-US** directory then that would be used first. Locale Detection ================ @@ -65,7 +65,7 @@ The first value tells the Request class that we do want to negotiate a locale, s Once this is enabled, the system will automatically negotiate the correct language based upon an array of locales that you have defined in ``$supportLocales``. If no match is found between the languages that you support, and the requested language, the first item in $supportedLocales will be used. In -the following example, the **en** locale would be used if no match is found: +the following example, the ``en`` locale would be used if no match is found: .. literalinclude:: localization/003.php @@ -80,7 +80,7 @@ segment will be your locale: .. literalinclude:: localization/004.php -In this example, if the user tried to visit ``http://example.com/fr/books``, then the locale would be +In this example, if the user tried to visit **http://example.com/fr/books**, then the locale would be set to ``fr``, assuming it was configured as a valid locale. If the value doesn't match a valid locale as defined in ``$supportedLocales`` in **app/Config/App.php**, the default From 58a5509bcadf91cc9ff92bc526207f57a93ee79b Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:52:30 +0900 Subject: [PATCH 8/9] docs: add `// ...` in sample code --- user_guide_src/source/outgoing/localization/001.php | 2 ++ user_guide_src/source/outgoing/localization/002.php | 2 ++ user_guide_src/source/outgoing/localization/003.php | 2 ++ 3 files changed, 6 insertions(+) diff --git a/user_guide_src/source/outgoing/localization/001.php b/user_guide_src/source/outgoing/localization/001.php index f03d25dc036f..4b0a000e3e44 100644 --- a/user_guide_src/source/outgoing/localization/001.php +++ b/user_guide_src/source/outgoing/localization/001.php @@ -6,6 +6,8 @@ class App extends BaseConfig { + // ... + public string $defaultLocale = 'en'; // ... diff --git a/user_guide_src/source/outgoing/localization/002.php b/user_guide_src/source/outgoing/localization/002.php index f4b4de2818f1..0113956ee4e3 100644 --- a/user_guide_src/source/outgoing/localization/002.php +++ b/user_guide_src/source/outgoing/localization/002.php @@ -6,6 +6,8 @@ class App extends BaseConfig { + // ... + public bool $negotiateLocale = true; // ... diff --git a/user_guide_src/source/outgoing/localization/003.php b/user_guide_src/source/outgoing/localization/003.php index 92d0d75e2e59..72f075a6da92 100644 --- a/user_guide_src/source/outgoing/localization/003.php +++ b/user_guide_src/source/outgoing/localization/003.php @@ -6,6 +6,8 @@ class App extends BaseConfig { + // ... + public array $supportedLocales = ['en', 'es', 'fr-FR']; // ... From aa8fc4861559d1e97d54d6b62b8a67522be719b0 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 2 Feb 2023 09:59:18 +0900 Subject: [PATCH 9/9] docs: add lang files --- user_guide_src/source/installation/upgrade_4xx.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/user_guide_src/source/installation/upgrade_4xx.rst b/user_guide_src/source/installation/upgrade_4xx.rst index 30ccd99f9089..24d4b0d2ea2a 100644 --- a/user_guide_src/source/installation/upgrade_4xx.rst +++ b/user_guide_src/source/installation/upgrade_4xx.rst @@ -41,7 +41,8 @@ Downloads Namespaces ========== -- CI4 is built for PHP 7.4+, and everything in the framework is namespaced, except for the helpers. +- CI4 is built for PHP 7.4+, and everything in the framework is namespaced, + except for the helper and lang files. Application Structure =====================