Skip to content

armgit / Filee

Public Imported from GitHub
0

Free, open-source file converter. Convert 263 formats offline by drag & drop — images, PDF, Word, Excel, PowerPoint, HWP/HWPX, video, audio, e-books and archives. No upload, no Office needed.

docs: record native localization and final verification evidence

BlackSpiritsb694dad8ada5
diff --git a/docs/ADDING-A-LANGUAGE.md b/docs/ADDING-A-LANGUAGE.md
index 4161e450..da86fc95 100644
--- a/docs/ADDING-A-LANGUAGE.md
+++ b/docs/ADDING-A-LANGUAGE.md
@@ -30,9 +30,29 @@ The Windows installer embeds the same JSON files, including the `installer.*` ke
currently has a separate, English-only text provider.
+Native macOS text also needs `<language>.lproj/ServicesMenu.strings` and, for permission explanations,
+`InfoPlist.strings`, plus a `CFBundleLocalizations` entry in `installer/macos/Info.plist`. Keep the English service
+identifier on the left of `ServicesMenu.strings`; translate its value. The packaging loop copies all `.lproj` folders
+and validates their strings files with `plutil`. These system texts follow macOS language preferences.
+Keep technical identifiers such as the KWin `Filee Donut` window title stable.
+
+
Optional, but welcome in the same or a later pull request: a translated README. Add `README.<code>.md` and link
it from the language line at the top of the other READMEs.
+## Demonstration recordings
+
+A slide may supply `localizedMedia` entries, for example
+`"pt-PT": { "media": "pt-PT/crop.webp", "poster": 57 }`. The code uses the exact UI language, otherwise the shared
+recording; regional variants do not borrow each other's recordings. Poster indices belong to each recording.
+The optional `FILEE_WHATSNEW_LANGUAGE` environment variable makes `WhatsNewMedia.Generate_2_0_0` generate a
+language's recordings and register them in the shared manifest. Rebuild App and Setup after generating them.
+The language-showcase slide intentionally demonstrates several languages and stays shared.
+
+Compact action names can use `preset.<name>.donut` when the donut already shows the target format underneath.
+Keep the full action name for the preset editor; custom names always take priority. `.short` is for a group's inner
+choices, whose group supplies additional context (Rotate → Left), and is a separate contract.
+
## Adding a UI string
Add the key to **all** language files in the same pull request. In XAML use
diff --git a/docs/PORTUGUESE-LOCALIZATION.md b/docs/PORTUGUESE-LOCALIZATION.md
index 8aea83d8..08e141c3 100644
--- a/docs/PORTUGUESE-LOCALIZATION.md
+++ b/docs/PORTUGUESE-LOCALIZATION.md
@@ -1,15 +1,16 @@
# Portuguese localization review
-Reviewed on 21 October 2026 against upstream `941b01bf5440bc2ff9a10dd00a4b9967d848d2ad`.
+Reviewed on 21 October 2026; integration now includes Filee 2.0.0 at upstream `799e39485f2aa78677f9ba51f692e862a7af76a6`.
The first implementation used `c63a261`, then integrated the installer at `85f7e56` on 20 October.
The 21 October review integrated `259c5ec`, then the newly merged Brazilian contribution at `941b01b`.
+The final release merge changes only the version and changelog; it adds no English strings.
This report covers Phase 1. Security, conversion fidelity and performance still require the separate Phase 2 audit.
## Coverage and editorial review
-Both Portuguese catalogs contain all **907 English keys**, in English key order: upstream's 889 entries and
-18 descriptive engine names that previously came directly from C# metadata. Those 18 keys are translated in
-all eleven registered languages, including the Arabic catalog introduced upstream during this work.
+Both Portuguese catalogs contain all **910 English keys**, in English key order: upstream's 889 entries and
+18 descriptive engine names that previously came directly from C# metadata and three contextual donut labels.
+These 21 added keys are translated in all eleven registered languages, including Arabic.
The second review compared every English/pt-PT/pt-BR entry and its interface context. It refined 47 existing
pt-PT entries and 51 pt-BR entries, in addition to translating 38 new upstream messages and updating six changed
@@ -82,6 +83,29 @@ numeric. Tests include Portuguese UI with US regional formatting. Count summarie
`Conversões: 1` and `1 s para terminar`; zero, one, two and twenty-one are checked. This is not a general CLDR
plural engine; future messages needing grammatical plural categories should add an explicit plural contract.
+## Native desktop localization
+
+The macOS bundle now declares both Portuguese variants and ships `ServicesMenu.strings` plus `InfoPlist.strings`
+in `pt-PT.lproj` and `pt-BR.lproj`. Finder's service title matches `general.context_menu_label`; the English service
+identifier remains unchanged so enabling/disabling the service and existing registrations still refer to the same
+service. The two permission explanations retain distinct Portuguese terminology:
+
+| English | pt-PT | pt-BR |
+| --- | --- | --- |
+| Convert with Filee | Converter com o Filee | Converter com o Filee |
+| Filee reads selected Finder files when you use a conversion shortcut. | O Filee lê os ficheiros selecionados no Finder quando utilizas um atalho de conversão. | O Filee lê os arquivos selecionados no Finder quando você usa um atalho de conversão. |
+| Filee detects your conversion shortcut and drag gesture to show the conversion menu. | O Filee deteta o atalho de conversão e o gesto de arrastar para mostrar o menu de conversão. | O Filee detecta o atalho de conversão e o gesto de arrastar para mostrar o menu de conversão. |
+
+These are three native strings per variant, additional to the 910 JSON entries. macOS chooses native bundle texts
+from its language preferences; these are not Avalonia resources switched by the app's JSON language setting.
+The existing packaging loop copies every `.lproj`; it now validates each strings file with `plutil` on macOS before
+copying. Cross-platform tests check declared folders, service identity, catalog consistency and variant-specific
+permission wording. Actual Finder and permission-prompt display still require a native desktop check.
+
+On Linux, `Filee Donut` is a technical window identifier used by the shipped KWin script. It must remain stable
+across UI languages. Two contract cases check the window title against that script and across a pt-PT/pt-BR switch.
+Visible toolbar strings remain localized.
+
## Reproduced findings
P0 = critical, P1 = high, P2 = medium, P3 = low. This localization review makes no P0/P1 claim about the wider app.
@@ -95,6 +119,7 @@ P0 = critical, P1 = high, P2 = medium, P3 = low. This localization review makes
| P2 | Descriptive engine names bypass localization through `Converter.DisplayName`. | Add 18 resource keys in every catalog, with metadata fallback for unknown engines; preserve brands. |
| P2 | The two icon-only preset actions lack explicit localized accessible names. | Bind automation names to existing translation keys and verify both variants. Native screen-reader behavior remains to be checked. |
| P3 | `pt-PT-x-br` and three related cases resolve to pt-BR because any later `BR` subtag is treated as a region. Four new resolver cases failed before the correction. | Interpret the region position, retaining script and legacy-code handling. Both App and Setup cover eight additional region/extension cases. |
+| P2 | The macOS bundle has no Portuguese `.lproj` resources or bundle declarations, so native service/permission text cannot use the Portuguese catalogs. Inspect `installer/macos` and the packaged bundle. | Add both regional resources and declarations, keeping the service identifier stable; validate resources and packaging. Native display is still pending. |
| P3 | A separate test language list can omit newly registered catalogs; duplicate JSON keys are silently overwritten. | Use the shared registry and verify file parity, unique keys, non-empty values and placeholders. Retain upstream's new registry/Arabic coverage rather than adding a competing list. |
Portuguese tests compare placeholder multiplicity, named tokens, newline counts and Unicode NFC normalization,
@@ -108,24 +133,39 @@ Recorded on Linux x64 with .NET SDK 10.0.402 and all **15 pinned Noto font files
| Check | Passed | Failed | Skipped |
| --- | ---: | ---: | ---: |
| Release solution build (14 projects) | — | 0 errors | — |
-| App localization, Portuguese UI and release/README contracts | 321 | 0 | 0 |
+| App localization, Portuguese UI and release/README contracts | 343 | 0 | 0 |
| Setup texts, UI states and language handoff | 66 | 0 | 1 |
| Core, full suite | 456 | 0 | 0 |
| CLI, full suite | 28 | 0 | 0 |
-| Platform, full suite | 46 | 0 | 5 |
+| Platform, full suite, including native resource contracts | 48 | 0 | 5 |
-These checks total **917 passed tests and 6 platform-specific skips**. The build reports ten existing warnings.
-The Windows-only installer-path assertion stays enabled on Windows. The final App selection includes caption
-wrapping and #322 integration (318 passes), plus three added Portuguese light/dark release-window cases. The
-seventeen-case release-window rerun also verifies existing languages; repeated cases are not counted again.
-An earlier targeted editor-caption rerun passed all 29 cases. Core/CLI/Platform production code did not change
-when #322 was integrated, so their completed full-suite results remain applicable.
+The focused/current checks total **941 unique passed tests and 6 platform-specific skips**. The App count is the
+341-case completed selection plus two new KWin language-contract cases. The final 163-case follow-up covers changed captions,
+localized resources and the release window; overlapping cases are not counted twice. Release builds complete with
+no errors and retain existing obsolete-API/nullability warnings. All 15 pinned fonts are present and verified.
+
+The broader Setup run on Linux completed **118 passed / 36 failed / 1 skipped**. Its 66 localization/UI/handoff
+passes above are included in those 118, so across all completed project checks there are **993 unique passes,
+36 failures and 6 skips**. This is not a green full-solution result. All 36 failure names exactly match a clean
+checkout of upstream `799e394`, running its non-UI Setup tests (**53 passed / 36 failed**). Windows-style fixture
+paths, Windows path normalization, PE imports and prior-install registry/path assumptions fail on Linux. No
+production installer-path behavior or test exclusions were changed to conceal them. The earlier Windows CI
+passed this suite; final Windows/native CI remains the appropriate check for these cases.
+
+Baseline reproduction, on Linux, from an untouched `799e394` checkout:
+
+```sh
+dotnet test tests/Filee.Setup.Tests -m:1 -c Release --filter "FullyQualifiedName!~SetupTextsTests&FullyQualifiedName!~SetupWindowTests"
+```
+
+The native desktop cases still need real Windows/macOS sessions. The build and resource tests alone cannot
+certify actual installation, UAC, Finder menus, permission dialogs or screen-reader behavior.
Reproduce the main checks from the repository root after fetching fonts with `build/fetch-fonts.ps1`:
```sh
dotnet build Filee.slnx -m:1 -c Release
-dotnet test tests/Filee.App.Tests -m:1 -c Release --filter "FullyQualifiedName~Localization|FullyQualifiedName~Portuguese|FullyQualifiedName~InstallerTests|FullyQualifiedName~SupportersTests|FullyQualifiedName~ReleaseNotesTests|FullyQualifiedName~WhatsNewTests|FullyQualifiedName~Home_page_search_finds_old_conversions_in_a_long_history|FullyQualifiedName~Watch_folder_options_rename_and_filter_with_a_preview|FullyQualifiedName~Preset_editor_shows_media_and_archive_options|FullyQualifiedName~One_picture_shows_the_frame_its_size_and_the_aspect_dial|FullyQualifiedName~Several_files_show_a_strip_with_how_each_went|FullyQualifiedName~Chooser_fits_long_paths_at_its_minimum_width|FullyQualifiedName~Live_photo_options_render_for_jpg_and_heic_and_save_only_there"
+dotnet test tests/Filee.App.Tests -m:1 -c Release --filter "FullyQualifiedName~Localization|FullyQualifiedName~Portuguese|FullyQualifiedName~InstallerTests|FullyQualifiedName~SupportersTests|FullyQualifiedName~ReleaseNotesTests|FullyQualifiedName~WhatsNewTests|FullyQualifiedName~DonutLabelPlacementTests|FullyQualifiedName~Home_page_search_finds_old_conversions_in_a_long_history|FullyQualifiedName~Watch_folder_options_rename_and_filter_with_a_preview|FullyQualifiedName~Preset_editor_shows_media_and_archive_options|FullyQualifiedName~One_picture_shows_the_frame_its_size_and_the_aspect_dial|FullyQualifiedName~Several_files_show_a_strip_with_how_each_went|FullyQualifiedName~Chooser_fits_long_paths_at_its_minimum_width|FullyQualifiedName~Live_photo_options_render_for_jpg_and_heic_and_save_only_there"
dotnet test tests/Filee.Setup.Tests -m:1 -c Release --filter "FullyQualifiedName~SetupTextsTests|FullyQualifiedName~SetupWindowTests|FullyQualifiedName~What_setup_hands_to_filee_is_what_filee_reads"
dotnet test tests/Filee.Core.Tests -m:1 -c Release
dotnet test tests/Filee.Cli.Tests -m:1 -c Release
@@ -133,8 +173,13 @@ dotnet test tests/Filee.Platform.Tests -m:1 -c Release
```
The full solution formatter cannot connect to Roslyn's build-host pipe here (`SocketException (13): Permission
-denied`, host exit 137). Folder-based whitespace verification of all changed C# files and
-`git diff --check` pass. The fork's CI has now started; its remote result must be checked independently.
+denied`, host exit 137). Folder-based whitespace verification of the changed C# files and
+`git diff --check` pass. On the previously published head `7a1813a`, the Windows CI job passed the full App suite (954 tests), Setup
+(155), Core (454 passed / 2 skipped), CLI (27 / 1), Platform (48 / 3) and Engines (1,385 / 93), along with the
+full formatter and installer sandbox. Eight of the nine CI jobs completed successfully. macOS Intel was cancelled
+while running the App suite, so the overall run was not green. Those are results for the earlier head, not a final
+CI certificate for the localized recordings added here. The Unix workflow now logs individual UI cases and captures
+crash/hang diagnostics, matching Windows' five-minute UI hang timeout. New-head CI must be checked separately.
This is not a clean full-solution test result. Earlier broad engine checks on `c63a261` recorded 1,139 passes,
6 failures and 40 skips; five failures reproduced on an untouched checkout, while the remaining LibreOffice case
@@ -142,6 +187,39 @@ passed in isolation. That is historical evidence, not validation of the newer en
unfiltered App runs also did not complete and encountered denied named-pipe sockets. The current completed App
run is the focused selection above. The CLI keeps its separate, English-only text provider.
+## Localized demonstration media
+
+The six single-language demonstrations in the 2.0.0 What's new window and installer now have recordings in both
+Portuguese variants. They are rendered from real Filee controls, not edited screenshots. The language showcase
+intentionally remains shared, since it demonstrates several languages. The original shared recordings are retained.
+
+Each slide can declare `localizedMedia`, keyed by the exact canonical UI language, with a relative `media` path and
+its own `poster` frame. Unknown languages use the shared recording; pt-PT never falls back to pt-BR. Invalid paths
+are ignored by the same relative-path validation used for shared media. The app refreshes the picture when its UI
+language changes, keeping the current slide. Setup uses its selected language too. Tests cover exact matching,
+invalid entries, live switches, keyboard navigation, every localized resource and each reduced-motion poster.
+
+The final visual pass found clipped image-action labels in the donut. Four new layout cases failed for the existing
+Portuguese names. Contextual `.donut` keys now give the ring compact names while the editor retains the full names
+and user-defined names retain priority:
+
+| English action | pt-PT / pt-BR ring label | Full Portuguese name retained in the editor |
+| --- | --- | --- |
+| Half size | Tamanho 50 % | Metade do tamanho |
+| Trace to SVG | Vetorizar | Vetorizar para SVG |
+| Line art to SVG | Traços | Traços para SVG |
+
+Six layout cases cover both variants and preserve custom names. Every media file stays below 400 KiB; each language
+pack and the shared pack stay below 2 MiB. Together they must stay below 6 MiB. Regenerate from a built test project:
+
+```sh
+FILEE_WHATSNEW_LANGUAGE=pt-PT dotnet tests/Filee.App.Tests/bin/Release/net10.0/Filee.App.Tests.dll -method 'Filee.App.Tests.WhatsNewMedia.Generate_2_0_0' -explicit only
+FILEE_WHATSNEW_LANGUAGE=pt-BR dotnet tests/Filee.App.Tests/bin/Release/net10.0/Filee.App.Tests.dll -method 'Filee.App.Tests.WhatsNewMedia.Generate_2_0_0' -explicit only
+```
+
+Rebuild after generation: the pictures are embedded in both App and Setup. Inspect the generated first-frame PNGs
+and the What's new / installer screenshots, including the selected poster frames.
+
## Visual and native checks
Headless Skia screenshots cover nine app pages in both variants at the 820 px minimum, light/dark themes and
@@ -156,14 +234,26 @@ labels and their field captions wrap. Real Windows/macOS desktops, installation/
technologies still need native verification. Headless rendering and simulated language providers cannot certify
that integration. The PR remains a draft for these checks and complete CI validation.
+### Remaining native verification
+
+The following checks need actual desktops; the headless tests and CI sandbox are not a substitute:
+
+- Windows display language pt-PT / pt-BR with `auto`, then an explicit opposite variant and a restart. Repeat with
+ a different number/date region and verify that language changes do not change the regional format.
+- Real Windows install, update, launch and uninstall in both variants, including UAC and the optional-engine page.
+ The automated installer sandbox uses a stub app and a scratch registry; it does not cover that full interaction.
+- macOS started from Finder with each Portuguese preferred language; check the explicit choice after restarting.
+- Tab / Shift+Tab, Enter and Escape through the language picker, preset editor and installation. With NVDA on
+ Windows and VoiceOver on macOS, confirm names, roles, focus and the two localized preset icon actions.
+
## Upstream coordination and next phase
-Merged upstream fixes/features are integrated through `941b01b`; no open feature branch is imported. Existing
+Merged upstream fixes/features are integrated through `799e394` (2.0.0); no open feature branch is imported. Existing
PRs #242, #249, #275, #282, #283 and #291 were checked earlier and have since been merged or closed.
[KnifeLemon/Filee#322](https://github.com/KnifeLemon/Filee/pull/322) merged during this review. Its Brazilian
README, release announcements and added coverage are integrated. The fork keeps the independently reviewed
-Brazilian catalog, with the same 889 upstream keys plus the 18 engine-name keys. Tests added by #322 that assumed
+Brazilian catalog, with the same 889 upstream keys plus the 18 engine-name keys and three contextual donut labels. Tests added by #322 that assumed
pt-PT should use Brazilian Portuguese are updated to distinguish the variants. Existing Brazilian UI cases are
retained without duplicating the render-data entries already present here.
@@ -172,8 +262,8 @@ and refines the Brazilian localization already present upstream. It targets this
should describe that final scope. The broad `pt` prefix fallback is replaced by the shared region policy, so an
unsupported code such as `ptx` does not accidentally select Portuguese.
-French is absent from current upstream catalogs and no open French PR was found. Adding it is reasonable as a
-separate localization contribution after the Portuguese/native checks. It is not part of this change.
+French is absent from current upstream catalogs, but [KnifeLemon/Filee#359](https://github.com/KnifeLemon/Filee/pull/359)
+now supplies it in an open contribution by another author. Do not duplicate that work. It is not imported here.
Phase 2 remains pending: untrusted inputs and archive extraction, processes/downloads, temporary files,
cancellation/concurrency, conversion fidelity/metadata/color, memory/performance, dependencies, packaging,