feat: add completion handler for localization changes and update documentation

[serhii-londar]

Note

Medium Risk
Changes the localization switching contract and refresh triggering behavior across the provider protocol, which could affect timing/side effects of language updates in apps and custom providers.

Overview
Adds a new completion-based API CrowdinSDK.setCurrentLocalization(_:completion:) so callers can be notified when a language switch and localization refresh finishes.

Refactors localization switching to flow through Localization.setCurrentLocalization(..., completion:) and a new LocalizationProviderProtocol.setLocalization(_:completion:), replacing the previous localization setter side-effect that auto-refreshed on didSet. Updates unit tests/mocks for the new protocol method and adds coverage that completion is called even when the SDK/provider isn’t initialized, and documents the new API in website/docs/setup.mdx.

^{Written by Cursor Bugbot for commit 8d78687. This will update automatically on new commits. Configure here.}

Closes #370

[Copilot]

Pull request overview

This PR adds a completion handler-based API for the setCurrentLocalization method, allowing developers to be notified when localization changes complete. This enables better UI synchronization when switching languages.

Changes:

• Added public setCurrentLocalization(_:completion:) method to CrowdinSDK class
• Refactored LocalizationProviderProtocol to make localization property read-only and added setLocalization(_:completion:) method
• Updated all protocol implementations (production and test mocks) to conform to the new protocol signature
• Added comprehensive test coverage for the new completion-based API
• Updated documentation with usage examples

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
Sources/CrowdinSDK/CrowdinSDK/CrowdinSDK.swift	Added public setCurrentLocalization(_:completion:) method with documentation
Sources/CrowdinSDK/CrowdinSDK/Localization/Localization.swift	Refactored internal localization setter to use new completion-based method
Sources/CrowdinSDK/CrowdinSDK/Localization/Provider/LocalizationProvider.swift	Changed protocol to make localization read-only, added setLocalization(_:completion:) method to protocol and implementation
Tests/UnitTests/MockLocalizationProvider.swift	Updated mock to implement new protocol method, fixed trailing whitespace
Tests/UnitTests/InitializationCompletionHandlerTests.swift	Added comprehensive tests for completion handler functionality
Sources/Tests/Core/BundleSwizzleReentrancyTests.swift	Updated test mocks to implement new protocol method
website/docs/setup.mdx	Added documentation and code example for the completion-based API

[codecov]

Codecov Report

❌ Patch coverage is 84.74576% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.22%. Comparing base (e2c07c1) to head (8d78687).

Files with missing lines	Patch %	Lines
...rces/Tests/Core/BundleSwizzleReentrancyTests.swift	0.00%	6 Missing ⚠️
...K/Localization/Provider/LocalizationProvider.swift	0.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #377      +/-   ##
==========================================
+ Coverage   55.83%   56.22%   +0.40%     
==========================================
  Files         136      136              
  Lines        6320     6377      +57     
==========================================
+ Hits         3528     3585      +57     
  Misses       2792     2792              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.