Skip to content

Commit b4ae9b2

Browse files
AzGasimAzGasim
committed
1 parent cc2edba commit b4ae9b2

8 files changed

Lines changed: 310 additions & 198 deletions

File tree

‎packages/localization/README.md‎

Lines changed: 206 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -17,175 +17,246 @@ Curious what the install command does? See manual installation below.
1717

1818
## What it does
1919

20-
- Will create a new table `localizations` with the following columns:
21-
- `language_id`
22-
- `routing_path`
23-
- `title`
24-
- `description`
25-
- `keywords`
26-
- `author`
27-
- `created_at`
28-
- `updated_at`
20+
- Creates the `localizations` table (language/locale routing, admin/frontend visibility, fallback behaviour, per-row display settings).
21+
- Integrates with `astrotomic/laravel-translatable` and `moox/core`.
22+
- Provides a **language selector** for Filament (flags + display names) and a Livewire **language switch** component.
23+
- Optional Localization Filament panel (`enable-panel` in config).
2924

30-
- Has dependencies to the `astrotomic/laravel-translatable` and `moox/core` package.
31-
- Has Language Switcher Livewire Component and LocalizationPanelProvider.
25+
## Language selector: names, flags, and settings
3226

27+
How Moox builds **display names** and **flag icons** for each localization, and how the Filament toggles relate to each other.
3328

34-
#### LocalizationPanelProvider
29+
### Where this appears
3530

36-
To use the LocalizationPanelProvider, you need to enable it in the config file:
31+
| Place | Attribute | Purpose |
32+
|-------|-----------|---------|
33+
| Admin language dropdown (`lang-selector` blade) | `display_name`, `display_flag` | Current language + list of alternatives |
34+
| Localization index table | `display_name`, `table_flag` | Overview of all locales |
35+
| Translation columns (Draft, News, Media, …) | `display_flag` | Per-locale flag in translation UI |
36+
| Filament create/edit form | Toggles + `use_country_icon` | Configure each localization |
3737

38-
```php
39-
'enable-panel' => true,
40-
```
41-
now the panel will be available at `/localization`
38+
The Livewire `language-switch` component currently shows **language codes only** (no flags). Use `display_flag` when adding flags there.
39+
40+
### Admin language selector (`lang-selector`)
4241

42+
For Filament resources with translations (Draft, News, Category, Media, etc.):
4343

44-
#### Language Switcher
45-
Include a Language switcher which wil rely on your created locales.
46-
To include it in filament panel
44+
```blade
45+
@include('localization::lang-selector')
4746
```
48-
->renderHook(
49-
\Filament\View\PanelsRenderHook::USER_MENU_BEFORE,
50-
fn (): string => \Illuminate\Support\Facades\Blade::render('@livewire(\'language-switch\',[\'context\'=>\'backend\'])'),
51-
);
47+
48+
Or register a render hook on your panel. The view loads active localizations (`is_active_admin` or `is_active_frontend`), shows `display_flag` and `display_name` on the trigger, and lists alternatives the same way. Pass `locale_variant` as the `lang` query parameter so the correct regional entry is selected.
49+
50+
### Two separate concerns
51+
52+
**Names** and **flags** are configured independently:
5253

5354
```
54-
or just use the livewire component in your blade view:
55-
```blade
56-
@livewire('language-switch',['context'=>'backend'])
55+
display_name ← use_native_names
56+
show_regional_variants
57+
use_country_translations
58+
59+
display_flag ← use_country_icon
60+
(+ language-specific exceptions, see below)
61+
```
62+
63+
**Regional** affects **names only**, not flags. Country vs language flags are controlled only by **Country flag** (`use_country_icon`).
64+
65+
### Database: `localizations` table
66+
67+
| Column | Type | Default | Role |
68+
|--------|------|---------|------|
69+
| `locale_variant` | string | required | e.g. `de_CH`, `en_US`, `fr_CH` |
70+
| `language_settings` | JSON | `null` | Per-row overrides for name settings |
71+
| `use_country_icon` | boolean | `false` | Per-row: country vs language icon |
72+
73+
Global defaults for `language_settings` keys: `config/localization.php` → `language_selector`.
74+
75+
### Display name (`display_name`)
76+
77+
Built by `Localization::getDisplayNameAttribute()`.
78+
79+
#### Native (`use_native_names`)
80+
81+
| On | Off |
82+
|----|-----|
83+
| `StaticLanguage::native_name` | `StaticLanguage::common_name` (usually English) |
84+
| Deutsch | German |
85+
86+
Config: `language_selector.use_native_names` (default: `true`).
87+
88+
#### Regional (`show_regional_variants`)
89+
90+
When **on** and `locale_variant` contains `_` (e.g. `de_CH`), appends the country in parentheses:
91+
92+
| On | Off |
93+
|----|-----|
94+
| Deutsch (Schweiz) | Deutsch |
95+
| English (United States) | English |
96+
97+
No effect when the locale has no region suffix (`de` only). Config: `language_selector.show_regional_variants` (default: `true`).
98+
99+
#### Country names (`use_country_translations`)
100+
101+
Only when **Regional** is on. Turning Regional off also turns Country names off. Controls the country part in parentheses:
102+
103+
| On | Off |
104+
|----|-----|
105+
| Translated name from `static_countries.translations` | `StaticCountry::common_name` |
106+
| Deutsch (Schweiz) | Deutsch (Switzerland) |
107+
108+
Config: `language_selector.use_country_translations` (default: `true`).
109+
110+
#### Name examples for `de_CH`
111+
112+
| Native | Regional | Country names | Result |
113+
|--------|----------|---------------|--------|
114+
| off | off | — | German |
115+
| on | off | — | Deutsch |
116+
| on | on | off | Deutsch (Switzerland) |
117+
| on | on | on | Deutsch (Schweiz) |
118+
119+
### Display flag (`display_flag` / `table_flag`)
120+
121+
Built by `Localization::resolveFlagIcon()`. `display_flag` and `table_flag` always use the **same logic**.
122+
123+
#### Country flag (`use_country_icon`)
124+
125+
| Value | Behaviour for `de_CH` |
126+
|-------|------------------------|
127+
| `false` (default) | Language flag → `flag-de` |
128+
| `true` | Country flag from locale suffix → `flag-ch` |
129+
130+
Country code = part after `_` in `locale_variant`, lowercased. Icon is used only if it exists (`flagExists()`).
131+
132+
#### Languages with a dedicated flag
133+
134+
Always use their language-specific icon, regardless of `use_country_icon`:
135+
136+
`ku`, `bo`, `eo`, `eu`, `cy`, `br`, `co`, `ar`, `aa`
137+
138+
#### Swiss site example (`de_CH`, `it_CH`, `fr_CH`)
139+
140+
| locale_variant | `use_country_icon` | Flag shown |
141+
|----------------|--------------------|------------|
142+
| `de_CH` | `false` | DE |
143+
| `it_CH` | `false` | IT |
144+
| `fr_CH` | `false` | FR |
145+
146+
With `use_country_icon` on all three, all show CH—usually not desired for a multilingual Swiss site.
147+
148+
### Filament resource toggles
149+
150+
| Column label | Setting | Affects |
151+
|--------------|---------|---------|
152+
| Native | `language_settings.use_native_names` | Name |
153+
| Regional | `language_settings.show_regional_variants` | Name |
154+
| Country names | `language_settings.use_country_translations` | Name (parentheses) |
155+
| Country flag | `use_country_icon` (DB column) | Flag icon |
156+
157+
Per-row `language_settings` override global config when a key is set on that record.
158+
159+
### Global configuration
160+
161+
```php
162+
// config/localization.php
163+
'language_selector' => [
164+
'use_native_names' => true,
165+
'show_regional_variants' => true,
166+
'use_country_translations' => true,
167+
],
168+
```
169+
170+
Publish: `php artisan vendor:publish --tag=localization-config`
171+
172+
`use_country_icon` is only per localization row (migration default: `false`).
173+
174+
### Programmatic access
175+
176+
```php
177+
use Moox\Localization\Models\Localization;
178+
179+
$localization = Localization::where('locale_variant', 'de_CH')->first();
180+
181+
$localization->display_name; // e.g. "Deutsch (Schweiz)"
182+
$localization->display_flag; // e.g. "flag-de"
183+
$localization->table_flag; // same as display_flag
184+
185+
$localization->getLanguageSetting('show_regional_variants'); // row or config fallback
186+
```
187+
188+
### Recommended defaults
189+
190+
| Scenario | Native | Regional | Country names | Country flag |
191+
|----------|--------|----------|---------------|--------------|
192+
| Swiss multilingual (`de_CH`, `it_CH`, `fr_CH`) | on | on | on | **off** |
193+
| Simple list, no region in UI | on | off | — | off |
194+
| Emphasize country over language (rare) | on | on | on | **on** |
195+
196+
### Related code
197+
198+
| File | Responsibility |
199+
|------|----------------|
200+
| `src/Models/Localization.php` | Names + flag resolution |
201+
| `resources/views/lang-selector.blade.php` | Admin dropdown |
202+
| `src/Filament/Resources/LocalizationResource.php` | Form and table toggles |
203+
| `config/localization.php` | Global name defaults |
204+
| `database/migrations/create_localizations_table.php.stub` | Schema |
205+
206+
## Localization panel
207+
208+
Enable in config:
209+
210+
```php
211+
'enable-panel' => true,
57212
```
58213

59-
#### LanguageMiddleware
214+
Panel URL: `/localization`
60215

61-
The LanguageMiddleware is used to set a session cookie for the language.
216+
## Language Switcher (Livewire)
62217

63-
#### Tabs and Translation
218+
Relies on locales marked active for admin or frontend. Text codes only today.
64219

65-
Moox Core features like Dynamic Tabs and Translatable Config. See the config file for more details, but as a quick example:
220+
Filament panel hook:
66221

67222
```php
68-
/*
69-
|--------------------------------------------------------------------------
70-
| Tabs
71-
|--------------------------------------------------------------------------
72-
|
73-
| Define the tabs for the Resource table. They are optional, but
74-
| pretty awesome to filter the table by certain values.
75-
| You may simply do a 'tabs' => [], to disable them.
76-
|
77-
*/
78-
79-
'tabs' => [
80-
'all' => [
81-
'label' => 'trans//core::core.all',
82-
'icon' => 'gmdi-filter-list',
83-
'query' => [
84-
[
85-
'field' => 'deleted_at',
86-
'operator' => '=',
87-
'value' => null,
88-
],
89-
],
90-
],
91-
'published' => [
92-
'label' => 'trans//core::core.published',
93-
'icon' => 'gmdi-check-circle',
94-
'query' => [
95-
[
96-
'field' => 'publish_at',
97-
'operator' => '<=',
98-
'value' => function () {
99-
return now();
100-
},
101-
],
102-
[
103-
'field' => 'deleted_at',
104-
'operator' => '=',
105-
'value' => null,
106-
],
107-
],
108-
],
109-
'scheduled' => [
110-
'label' => 'trans//core::core.scheduled',
111-
'icon' => 'gmdi-schedule',
112-
'query' => [
113-
[
114-
'field' => 'publish_at',
115-
'operator' => '>',
116-
'value' => function () {
117-
return now();
118-
},
119-
],
120-
[
121-
'field' => 'deleted_at',
122-
'operator' => '=',
123-
'value' => null,
124-
],
125-
],
126-
],
127-
'draft' => [
128-
'label' => 'trans//core::core.draft',
129-
'icon' => 'gmdi-text-snippet',
130-
'query' => [
131-
[
132-
'field' => 'publish_at',
133-
'operator' => '=',
134-
'value' => null,
135-
],
136-
[
137-
'field' => 'deleted_at',
138-
'operator' => '=',
139-
'value' => null,
140-
],
141-
],
142-
],
143-
'deleted' => [
144-
'label' => 'trans//core::core.deleted',
145-
'icon' => 'gmdi-delete',
146-
'query' => [
147-
[
148-
'field' => 'deleted_at',
149-
'operator' => '!=',
150-
'value' => null,
151-
],
152-
],
153-
],
154-
],
155-
],
223+
->renderHook(
224+
\Filament\View\PanelsRenderHook::USER_MENU_BEFORE,
225+
fn (): string => \Illuminate\Support\Facades\Blade::render('@livewire(\'language-switch\',[\'context\'=>\'backend\'])'),
226+
)
156227
```
157228

158-
All options for Tabs are explained in [Moox Core docs](https://github.com/mooxphp/core/blob/main/README.md#dynamic-tabs).
229+
Blade:
230+
231+
```blade
232+
@livewire('language-switch', ['context' => 'backend'])
233+
```
159234

160-
## Manual Installation
235+
## Tabs and translation
161236

162-
Instead of using the install-command `php artisan localization:install` you are able to install this package manually step by step:
237+
Moox Core features like Dynamic Tabs and Translatable Config. See the config file; [Moox Core docs](https://github.com/mooxphp/core/blob/main/README.md#dynamic-tabs) explain tabs.
238+
239+
## Manual installation
163240

164241
```bash
165-
// Publish and run the migrations:
166242
php artisan vendor:publish --tag="localization-migrations"
167243
php artisan migrate
168244

169-
// Publish the config file with:
170245
php artisan vendor:publish --tag="localization-config"
171246
```
172-
## use it
173-
174-
We are requiring astrotomic/laravel-translatable
175-
to use it see doc: https://docs.astrotomic.info/laravel-translatable
176247

177-
## Changelog
248+
## Astrotomic translatable
178249

179-
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
250+
We require [astrotomic/laravel-translatable](https://docs.astrotomic.info/laravel-translatable).
180251

181-
## Security Vulnerabilities
252+
## Changelog
182253

183-
Please review [our security policy](https://github.com/mooxphp/moox/security/policy) on how to report security vulnerabilities.
254+
See [CHANGELOG](CHANGELOG.md).
184255

185-
## Credits
256+
## Security
186257

187-
- [All Contributors](../../contributors)
258+
See [security policy](https://github.com/mooxphp/moox/security/policy).
188259

189260
## License
190261

191-
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
262+
MIT — see [LICENSE](LICENSE.md).

0 commit comments

Comments
 (0)