Skip to content

Commit 962c3d1

Browse files
BelimBelim
committed
Init Winslop.WinUI localized
1 parent 6a6880e commit 962c3d1

3 files changed

Lines changed: 981 additions & 0 deletions

File tree

‎Winslop.WinUI/Winslop/Strings/LOCALIZATION.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Localization Guide
2+
3+
Winslop uses the standard WinUI 3 resource system (`.resw` files) for translations.
4+
This guide explains how translations work and how you can contribute.
5+
6+
---
7+
8+
## For Translators
9+
10+
You don't need Visual Studio, C#, or any programming knowledge.
11+
All you need is a text editor and a GitHub account.
12+
13+
### How translation files work
14+
15+
Every language has its own folder under `Strings/` with a `Resources.resw` file:
16+
17+
```
18+
Strings/
19+
en-US/Resources.resw <-- English (default)
20+
de-DE/Resources.resw <-- German
21+
```
22+
23+
The `.resw` file is simple XML. Each line has a **key** (don't touch) and a
24+
**value** (translate this):
25+
26+
```xml
27+
<data name="NavHome.Text"><value>Home</value></data>
28+
```
29+
30+
The file is organized in clearly labeled sections so you always know
31+
what part of the app you're translating:
32+
33+
```xml
34+
<!-- XAML x:Uid: MainWindow — Navigation -->
35+
<!-- XAML x:Uid: InstallPage -->
36+
<!-- C# ResourceLoader: Donation dialog -->
37+
```
38+
39+
### How to create a translation
40+
41+
1. **Copy** `Strings/en-US/Resources.resw` into a new folder, e.g. `Strings/fr-FR/`
42+
2. **Translate** every `<value>...</value>` — do NOT change the `name` attributes
43+
3. **Keep placeholders** like `{0}`, `{1}` — they get replaced with numbers/text at runtime
44+
4. **Keep special characters** like `&lt;` (this is `<` in XML) and `&#x2764;` (heart emoji)
45+
5. **Don't translate** brand names: Winslop, Copilot, Edge, Ko-fi, PayPal, CFEnhancer
46+
47+
**Example:**
48+
49+
```xml
50+
<!-- English original -->
51+
<data name="BtnAnalyzeText.Text"><value>Inspect system</value></data>
52+
<data name="Tools_Loaded"><value>{0} extensions loaded.</value></data>
53+
54+
<!-- French translation -->
55+
<data name="BtnAnalyzeText.Text"><value>Inspecter le système</value></data>
56+
<data name="Tools_Loaded"><value>{0} extensions chargées.</value></data>
57+
```
58+
59+
### How to submit your translation
60+
61+
1. Fork the repo: https://github.com/builtbybel/Winslop
62+
2. Add your `Strings/<locale>/Resources.resw` file
63+
3. Open a Pull Request with the title: **Add \<Language\> translation**
64+
65+
That's it! The developer will handle the project configuration, menu entry,
66+
and compilation. You just provide the translated `.resw` file.
67+
68+
**Tips for a good translation:**
69+
- Keep the same tone — Winslop is informal and direct
70+
- The section comments in the file tell you which page each group belongs to
71+
- If a value looks technical or unclear, check the English version in context
72+
by looking at the section header (e.g. "ToolsPage", "Donation dialog")
73+
74+
---
75+
76+
## For Developers
77+
78+
Technical details for integrating a new language into the build and UI.
79+
80+
### 1. Register the language
81+
82+
Add the locale to `SatelliteResourceLanguages` in `Winslop.csproj`:
83+
84+
```xml
85+
<SatelliteResourceLanguages>en-US;de-DE;fr-FR</SatelliteResourceLanguages>
86+
```
87+
88+
### 2. Add a menu entry
89+
90+
In `MainWindow.xaml`, add a new `MenuFlyoutItem` inside the language
91+
switcher `MenuFlyoutSubItem`:
92+
93+
```xml
94+
<MenuFlyoutItem x:Name="menuLangFrench" Text="Français" Click="MenuLangFrench_Click">
95+
<MenuFlyoutItem.Icon>
96+
<FontIcon x:Name="iconLangFrench" Glyph="&#xE73E;" Visibility="Collapsed" />
97+
</MenuFlyoutItem.Icon>
98+
</MenuFlyoutItem>
99+
```
100+
101+
### 3. Add the click handler
102+
103+
In `MainWindow.xaml.cs`:
104+
105+
```csharp
106+
private async void MenuLangFrench_Click(object sender, RoutedEventArgs e)
107+
{
108+
await Localizer.SwitchLanguageAsync("fr-FR", Content.XamlRoot);
109+
UpdateLanguageCheckmarks();
110+
}
111+
```
112+
113+
Update `UpdateLanguageCheckmarks()` to include the new icon:
114+
115+
```csharp
116+
if (iconLangFrench != null)
117+
iconLangFrench.Visibility = lang == "fr-FR" ? Visibility.Visible : Visibility.Collapsed;
118+
```
119+
120+
### 4. Build and test
121+
122+
Build the project. `MakePri` automatically compiles all `.resw` files
123+
into `Winslop.pri`. Switch to the new language via **Settings > Language**
124+
and restart the app.
125+
126+
### Key types reference
127+
128+
| Pattern | Used by | Example |
129+
|---|---|---|
130+
| `Name.Property` | XAML `x:Uid` (auto-applied at load) | `NavHome.Text`, `SearchBox.PlaceholderText` |
131+
| `Name` | C# via `Localizer.Get()` / `GetFormat()` | `Analysis_Complete`, `Tools_Loaded` |
132+
133+
### File structure
134+
135+
| File | Purpose |
136+
|---|---|
137+
| `Strings/en-US/Resources.resw` | English strings (fallback) |
138+
| `Strings/de-DE/Resources.resw` | German strings |
139+
| `Helpers/Localizer.cs` | `Get()`, `GetFormat()`, `SwitchLanguageAsync()`, `CurrentLanguage` |
140+
| `Helpers/SettingsHelper.cs` | Persists language choice to `Winslop.txt` |
141+
| `App.xaml.cs` | Applies `PrimaryLanguageOverride` on startup |
142+
143+
---
144+
145+
## Questions?
146+
147+
Open an issue at https://github.com/builtbybel/Winslop/issues

0 commit comments

Comments
 (0)