Skip to content

Commit 11ff23f

Browse files
Mohammad-AlaviMohammad-Alavi
committed
docs: update localization
API-504
1 parent a9e97f1 commit 11ff23f

File tree

2 files changed

+216
-224
lines changed

2 files changed

+216
-224
lines changed

‎docs/pacakges/localization.md

+108-112
Original file line numberDiff line numberDiff line change
@@ -3,161 +3,157 @@ sidebar_position: 2
33
title: Localization
44
---
55

6-
Languages are not real Components, they are just files that holds translations.
6+
The Localization Container is built on top of Laravel's [localization](https://laravel.com/docs/localization) features
7+
and provides a convenient way to create and manage translations for your application.
78

8-
Laravel localization features provide a convenient way to retrieve strings in various languages, allowing you to easily support multiple languages within your application.
9+
## Requirements
910

10-
## Rules
11+
`Intl` PHP Extension is required to use this feature.
1112

12-
- Languages CAN be placed inside the Containers. However, the default laravel `resources/lang` languages files are still loaded and can be used as well.
13+
## Installation
1314

14-
- All Translations are namespaced as the camelCase of its Section name + `@` + camelCase of its Container name.
15-
For example, translation key inside a translation file named `messages` inside `MySection` > `MyContainer` can be accessed like this: `__(mySection@myContainer::messages.welcome)`
15+
```
16+
composer require apiato/localization-container
17+
```
18+
19+
## Publishing Configs
20+
```
21+
php artisan vendor:publish
22+
```
23+
Config file will be placed at `app/Ship/Configs/vendor-localization.php`
1624

1725
## Folder Structure
1826

27+
```markdown
28+
app
29+
└── Containers
30+
└── Section
31+
└── Container
32+
└── Languages
33+
├── en
34+
│ ├── messages.php
35+
│ ├── users.php
36+
│ └── ...
37+
├── ar
38+
│ ├── messages.php
39+
│ ├── users.php
40+
│ └── ...
41+
└── ...
1942
```
20-
- app
21-
- Containers
22-
- {Section}
23-
- {Container}
24-
- Resources
25-
- Languages
26-
- en
27-
- messages.php
28-
- users.php
29-
- ar
30-
- messages.php
31-
- users.php
43+
44+
## Usage
45+
46+
All Translations are namespaced with the following pattern:
47+
```shell
48+
camelCase of its Section name + `@` + camelCase of its Container name
3249
```
3350

34-
## Usage {#usage}
51+
Let's say we have a `welcome` translation key in the `app/Containers/MySection/MyContainer/en/messages.php` file.
3552

53+
You can retrieve this translation like this:
3654
```php
37-
__('myS
38-
ection@myContainer::messages.welcome');
55+
__('mySection@myContainer::messages.welcome');
3956
```
4057

41-
## Installation{#installation}
4258
:::note
43-
Intl PHP Extension is required to use this feature.
59+
Translation files in **Ship** folder are exception to this and will be namespaced with the word "**ship**"
60+
instead of section name, e.g. `__('ship::messages.welcome')`
4461
:::
4562

46-
```
47-
composer require apiato/localization-container
48-
```
49-
## Creating new languages files {#create-new-languages-files}
63+
## Adding New Languages
5064

51-
Languages file can be placed in any container, not only the Localization Container.
52-
Place language files inside the `/Languages` folder of your container. For example
53-
`app/Containers/Section/Container/Languages`.
65+
Language files can be placed in any container's `Languages` folder.
5466
You can also place general language files in `app/Ship/Languages`.
67+
The language files placed in the default Laravel `lang` folder are still loaded and can be used as well.
5568

56-
:::note
57-
Just create the `Languages` folder if it does not exist in your container or `app/Ship` folder.
58-
:::
69+
These language folders work exactly the same way as the default Laravel `lang` folder.
5970

60-
You can still use the default Laravel translations by placing language files in `/lang` folder.
71+
:::note
72+
Just create the `Languages` folder if it does not exist in your container or the `app/Ship` directory.
73+
:::
6174

62-
## Support new languages{#support-new-languages}
75+
## Supporting New Languages
6376

6477
All supported languages must be added to the `supported_languages` array in the `vendor-localization.php` config file
65-
to prevent users from requesting unsupported languages. There are 2 ways to do this: Using the configs or by modifying the source code.
78+
to prevent users from requesting unsupported languages.
6679

6780
```php
68-
'supported_languages' => [
69-
'ar',
70-
'en' => [
71-
'en-GB',
72-
'en-US',
73-
],
74-
'es',
75-
'fr',
76-
'fa',
81+
'supported_languages' => [
82+
'ar',
83+
'en' => [
84+
'en-GB',
85+
'en-US',
7786
],
87+
'es',
88+
'fr',
89+
'fa',
90+
],
7891
```
7992

80-
### Publishing configs
81-
```
82-
php artisan vendor:publish
83-
```
84-
Config file will be copied to `app/Ship/Configs/vendor-localization.php`
85-
86-
### Modifying the source code {#modify-code}
87-
88-
1- Copy the container from `Vendor` to `AppSection` (or any of your custom sections) of your project
89-
2- Fix the namespaces
90-
3- Remove `apiato/localization-container` dependency from project root composer.json
91-
92-
## Select Request Language{#select-request-language}
93+
## Requesting a Specific Language
9394

9495
You can select the language of the response by adding the header `Accept-Language` to the request. By default, the
9596
`Accept-Language` is set to the language defined in `config/app.php` `locale`.
9697

97-
Please note that `Accept-Language` only determines, that the client _would like_ to get the information in this specific
98-
language. It is not given, that the API responds in this language!
99-
100-
When the `Accept-Language` header is missing, the default locale will be applied.
98+
Please note
99+
that the `Accept-Language` only declares that the client _would like_ to get the information in this specific language.
100+
It is not a given that the API responds in that language!
101101

102102
:::note
103103
Please be sure that your client does not send an `Accept-Language` header automatically. Some REST clients
104104
(e.g., `POSTMAN`) automatically add header-fields based on the operating-systems settings. So your `Accept-Language` header
105105
may be set automatically without you knowing!
106106
:::
107107

108-
The API will answer with the applied language in the `Content-Language` header of the response.
109-
110-
If the requested language cannot be resolved (e.g. it is not defined) the API throws an `UnsupportedLanguageException` to tell
111-
the client about this.
108+
Now that we have a `Accept-Language` set,
109+
the API will answer with the applied language in the `Content-Language` header of the response.
110+
And if the requested language cannot be resolved (e.g., it is not defined),
111+
an `UnsupportedLanguageException` will be thrown.
112112

113113
The overall workflow of the Middleware is as follows:
114114
1) Extract the `Accept-Language` field from the request header. If none is set, use the default locale from the config file
115115
2) Build a list of all supported localizations based on the configuration of the respective container. If a language
116116
(top level) contains regions (sub-level), order them like this: `['en-GB', 'en-US', 'en']` (the regions before languages,
117117
as regions are more specific)
118-
3) Check, if the value from 1) is within the list from 2). If the value is within this list, set it as application language,
119-
if not throw an `Exception`.
120-
121-
## Translating Strings{#translating-strings}
122-
123-
By default, all the Container translation files are namespaced as the camelCase of its Section name + `@` + camelCase of its Container name.
124-
125-
:::note
126-
Translation files in **Ship** folder are exception to this and will be namespaced with the word "**ship**" instead of section name, e.g. `__('ship::notifications.welcome')`
127-
:::
128-
129-
## Example
130-
131-
If a translation file called `notifications` is inside `MySection` > `MyContainer` that contains translation for `welcome`
132-
like "Welcome to our store :)". You can access this translation as follows `__('mySection@myContainer::notifications.welcome')`. If
133-
you remove the namespace (part before `::`) and try to access it like this
134-
`__('notifications.welcome')` it will not find your translation and will print `notifications.welcome` only.
135-
136-
:::note
137-
If you try to load a string for a language that is **not available** (e.g., there is no folder for this language), Apiato
138-
will stick to the default one that is defined in `app.locale` config file. This is also true, if the requested locale
139-
is present in the `supported_languages` array from the configuration file.
140-
:::
141-
142-
## Enable/Disable Localization{#enable-disable-localization}
143-
When using this container, Localization is **enabled** by default.
144-
To disable it set `LOCALIZATION_ENABLED` to `false` in the `.env` file.
145-
You can also change this behaviour in the [configs](#publishing-configs).
146-
This will disable the localization middleware.
147-
148-
## Get Available Localizations{#get-available-localizations}
149-
150-
This container provides a convenient way to get all defined localizations. These localizations can be retrieved via `GET /localizations`
151-
by default. Note that this route only outputs the "top level" locales, like `en` from the example above. However, if
152-
specific regions (e.g., `en-US`) are defined, these will show up in the result as well.
153-
154-
The `Transformer` for the localizations not only provide the `language` (e.g., `de`), but also outputs the name of the
155-
language in this specific language (e.g., `locale_name => Deutsch`). Furthermore, the language name is outputted in the
156-
applications default name (e.g., configured in `app.locale`). This would result in `default_name => German`.
157-
158-
The same applies to the regions that are defined (e.g., `de-DE`). Consequently, this results in `locale_name => Deutschland`
159-
and `default_name = Germany`.
160-
161-
## Tests{#tests}
162-
163-
To change the default language in your tests requests. You can set the `env` language in the `phpunit.xml` file.
118+
3) Check if the requested language is supported.
119+
If the language is supported, set it as application language, if not throw an `Exception`.
120+
121+
## Enable/Disable Localization
122+
123+
To enable or disable the localization,
124+
you can set the `LOCALIZATION_ENABLED` environment variable in the `.env` file
125+
to `true` or `false` respectively.
126+
This can also be done in the `vendor-localization.php` config file.
127+
128+
## Retrieve Available Localizations
129+
130+
Available localizations can be retrieved via `GET /localizations` endpoint.
131+
132+
You will get a response like this:
133+
```json
134+
{
135+
"data": [
136+
{
137+
"object": "Localization",
138+
"id": "de", // The language code (same as 'language.code')
139+
"language": {
140+
"code": "de", // The language code
141+
"default_name": "German", // The language name in the application's default language
142+
"locale_name": "Deutsch" // The language name in its native form
143+
"regions": [
144+
{
145+
"code": "de-DE", // The region code
146+
"default_name": "Germany", // The region name in the application's default language
147+
"locale_name": "Deutschland" // The region name in its native form
148+
},
149+
{
150+
"code": "de-AT", // The region code
151+
"default_name": "Austria", // The region name in the application's default language
152+
"locale_name": "Österreich" // The region name in its native form
153+
}
154+
]
155+
}
156+
}
157+
]
158+
}
159+
```

0 commit comments

Comments
 (0)