210 lines
7.1 KiB
Markdown
210 lines
7.1 KiB
Markdown
# SufiBlazor Localization
|
|
|
|
SufiBlazor uses **Microsoft.Extensions.Localization** so the component library works in any Blazor app—with or without ABP. All user-facing strings in Sb components are localized via a single resource and can be overridden by the host application.
|
|
|
|
## Overview
|
|
|
|
- **No ABP dependency** — Sb does not reference ABP; localization is based on `IStringLocalizer<T>` and `.resx` files.
|
|
- **Single resource** — `SufiBlazorResource` with embedded `.resx` (default English) and culture-specific `.resx` for **fa** (Persian) and **ar** (Arabic).
|
|
- **Host override** — Host apps can keep the built-in strings, add languages, or replace them via their own resource/JSON (e.g. ABP virtual JSON).
|
|
|
|
## Resource and Files
|
|
|
|
| Item | Location |
|
|
|------|----------|
|
|
| Marker class | `SufiChain.SufiBlazor.Localization.SufiBlazorResource` |
|
|
| Default (en) | `Localization/SufiBlazorResource.resx` |
|
|
| Persian | `Localization/SufiBlazorResource.fa.resx` |
|
|
| Arabic | `Localization/SufiBlazorResource.ar.resx` |
|
|
|
|
Components inject `IStringLocalizer<SufiBlazorResource>` (typically as `L`) and use `L["Key"]` or `L["Key", arg0, arg1]` for parameterized strings.
|
|
|
|
## How Components Use Localization
|
|
|
|
### Injecting the localizer
|
|
|
|
In any Sb component that shows localized text:
|
|
|
|
```razor
|
|
@inject IStringLocalizer<SufiBlazorResource> L
|
|
```
|
|
|
|
`_Imports.razor` already has `@using Microsoft.Extensions.Localization` and `@using SufiChain.SufiBlazor.Localization`, so `L` is available once injected.
|
|
|
|
### Displaying text
|
|
|
|
- **Simple:** `@L["Clear"]`, `@L["Close"]`
|
|
- **With parameters:** `@L["FilterBy", ColumnTitle]`, `@L["Opacity", _opacity]`
|
|
- **Fallback for nullable parameters:** `@(Placeholder ?? L["Select_Placeholder"])`
|
|
|
|
### Parameter pattern
|
|
|
|
Text parameters (placeholders, button labels, aria-labels) are `string?`. When null, the component uses the localized default:
|
|
|
|
```razor
|
|
[Parameter]
|
|
public string? Placeholder { get; set; }
|
|
|
|
// In markup:
|
|
@(Placeholder ?? L["Select_Placeholder"])
|
|
```
|
|
|
|
Callers can still pass an explicit value to override the default.
|
|
|
|
## Key Naming Conventions
|
|
|
|
| Convention | Example | Use |
|
|
|------------|---------|-----|
|
|
| PascalCase | `Clear`, `Cancel`, `Apply` | Buttons, actions, aria-labels |
|
|
| Noun_Placeholder | `Select_Placeholder`, `Search_Placeholder` | Default placeholder when parameter is null |
|
|
| Filter* | `FilterEquals`, `FilterContains`, `FilterBy` | Data grid / filter UI |
|
|
| Page* | `FirstPage`, `ItemsPerPage`, `PageInfoFormat` | Pagination |
|
|
| *Format | `PageAriaLabelFormat`, `PageInfoFormat`, `Opacity` | Strings with `{0}`, `{1}` placeholders |
|
|
|
|
When adding new keys, add them to all three `.resx` files (default, `.fa.resx`, `.ar.resx`).
|
|
|
|
## Resource Keys Reference
|
|
|
|
### Actions and common UI
|
|
|
|
| Key | Default (en) |
|
|
|-----|----------------|
|
|
| Clear | Clear |
|
|
| Close | Close |
|
|
| Cancel | Cancel |
|
|
| Apply | Apply |
|
|
| Save | Save |
|
|
| Expand | Expand |
|
|
| Collapse | Collapse |
|
|
| Remove | Remove |
|
|
| Yes | Yes |
|
|
| No | No |
|
|
| Confirm | Confirm |
|
|
| Back | Back |
|
|
| Next | Next |
|
|
| Previous | Previous |
|
|
| Finish | Finish |
|
|
| Optional | Optional |
|
|
| ClearAll | Clear all |
|
|
|
|
### Placeholders
|
|
|
|
| Key | Default (en) |
|
|
|-----|----------------|
|
|
| Select_Placeholder | Select... |
|
|
| Search_Placeholder | Search... |
|
|
| SelectDate_Placeholder | Select date... |
|
|
| SelectDateRange_Placeholder | Select date range... |
|
|
| SelectTime_Placeholder | Select time... |
|
|
| SelectColor_Placeholder | Select color... |
|
|
| EnterValue_Placeholder | Enter value... |
|
|
| EnterSlug_Placeholder | enter-slug-here |
|
|
|
|
### Forms and accessibility
|
|
|
|
| Key | Default (en) |
|
|
|-----|----------------|
|
|
| ShowPassword | Show password |
|
|
| HidePassword | Hide password |
|
|
| ClearTime | Clear time |
|
|
| ClearColor | Clear color |
|
|
| ClearDate | Clear date |
|
|
| ClearDates | Clear dates |
|
|
| Hour | Hour |
|
|
| Minute | Minute |
|
|
| Second | Second |
|
|
| Period | Period |
|
|
| Now | Now |
|
|
| CustomColor | Custom Color |
|
|
| Opacity | Opacity: {0}% |
|
|
| Preview | Preview: |
|
|
| GenerateSlug | Generate |
|
|
| GenerateFromTitle | Generate from title |
|
|
| NoResultsFound | No results found |
|
|
|
|
### Data grid and pagination
|
|
|
|
| Key | Default (en) |
|
|
|-----|----------------|
|
|
| FirstPage | First page |
|
|
| PreviousPage | Previous page |
|
|
| NextPage | Next page |
|
|
| LastPage | Last page |
|
|
| ItemsPerPage | Items per page: |
|
|
| NoItems | No items |
|
|
| PageAriaLabelFormat | Page {0} |
|
|
| PageInfoFormat | {0}-{1} of {2} |
|
|
| SaveChanges | Save changes |
|
|
| CancelEditing | Cancel editing |
|
|
| EditRow | Edit row |
|
|
|
|
### Filter menu
|
|
|
|
| Key | Default (en) |
|
|
|-----|----------------|
|
|
| Operator | Operator |
|
|
| Value | Value |
|
|
| And | And |
|
|
| FilterBy | Filter: {0} |
|
|
| FilterOptions | Filter options |
|
|
| FilterEquals | Equals |
|
|
| FilterNotEquals | Not equals |
|
|
| FilterContains | Contains |
|
|
| FilterStartsWith | Starts with |
|
|
| FilterEndsWith | Ends with |
|
|
| FilterGreaterThan | Greater than |
|
|
| FilterGreaterThanOrEqual | Greater than or equal |
|
|
| FilterLessThan | Less than |
|
|
| FilterLessThanOrEqual | Less than or equal |
|
|
| FilterBetween | Between |
|
|
| FilterInList | In list |
|
|
| FilterIsEmpty | Is empty |
|
|
| FilterIsNotEmpty | Is not empty |
|
|
|
|
## Localized Components
|
|
|
|
Components that use `L` and the keys above include:
|
|
|
|
- **Forms:** SbTextField, SbAutocomplete, SbSelect, SbMultiSelect, SbSimpleSelect, SbTimePicker, SbColorPicker, SbDatePicker, SbDateRangePicker, SbSlugEditor, SbRichTextEditor (link/image dialog Cancel/Apply)
|
|
- **Overlays:** SbDialog, SbDrawer, SbToast, SbConfirmDialog
|
|
- **Data:** SbDataGrid (row edit Save/Cancel/Edit), SbPagination, SbColumnFilterMenu, SbFilterBar
|
|
- **Navigation:** SbTreeViewNode (Expand/Collapse), SbStepper (Back/Next/Finish/Optional)
|
|
|
|
## Host Application Setup
|
|
|
|
### Non-ABP Blazor app
|
|
|
|
1. Call `AddSufiBlazor()` — it registers `AddLocalization()`.
|
|
2. Configure request localization (e.g. middleware and `RequestLocalizationOptions`) as needed for your app.
|
|
3. Sb components will use `IStringLocalizer<SufiBlazorResource>` and the embedded `.resx` for the current culture.
|
|
|
|
### ABP host
|
|
|
|
1. ABP already registers localization; using `AddSufiBlazor()` is enough for the built-in Sb strings.
|
|
2. To **override** Sb strings with your own (e.g. JSON):
|
|
|
|
```csharp
|
|
Configure<AbpLocalizationOptions>(options =>
|
|
{
|
|
options.Resources
|
|
.Add<SufiBlazorResource>("en")
|
|
.AddVirtualJson("/Localization/SufiBlazor");
|
|
});
|
|
```
|
|
|
|
Then add your JSON files under the path you specified; they will take precedence over the embedded `.resx` for that culture.
|
|
|
|
## Adding a New Localized String
|
|
|
|
1. **Choose a key** — Use PascalCase or the existing conventions (e.g. `Noun_Placeholder`, `Filter*`).
|
|
2. **Add to all three .resx files** in `src/modules/sufi-blazor/src/SufiChain.SufiBlazor/Localization/`:
|
|
- `SufiBlazorResource.resx` (default/en)
|
|
- `SufiBlazorResource.fa.resx`
|
|
- `SufiBlazorResource.ar.resx`
|
|
3. **Use in component:** `@L["YourKey"]` or `@(YourParameter ?? L["YourKey"])`.
|
|
4. If the component does not yet inject the localizer, add `@inject IStringLocalizer<SufiBlazorResource> L`.
|
|
|
|
## RTL
|
|
|
|
Persian (fa) and Arabic (ar) are RTL. Sb layout and theme handle RTL via `SbThemeProvider` and `Direction`; localization only provides the translated strings. Ensure the app sets the correct culture and direction for the UI.
|