f8-features-localization-workflow

name	f8-features-localization-workflow
description	Use when implementing or troubleshooting Localization feature workflows — multi-language support, component localization, Excel-based translation tables in F8Framework.

Localization Feature Workflow

⚠️ IMPORTANT: Before using this feature, you MUST formally initialize F8Framework in the launch sequence. Ensure ModuleCenter.Initialize(this); has run first, then create the required module, for example FF8.Local = ModuleCenter.CreateModule<Localization>(F8DataManager.Instance.GetLocalizedStrings());.

Use this skill when

• The task is about multi-language support, language switching, or localized assets.
• The user asks about Text/Image/Audio localization or Excel translation tables.

Path resolution

1. Prefer project source at Assets/F8Framework.
2. For usage docs, read: Assets/F8Framework/Tests/Localization/README.md

Sources of truth

• Runtime module: Assets/F8Framework/Runtime/Localization
• Editor module: Assets/F8Framework/Editor/Localization
• Test docs: Assets/F8Framework/Tests/Localization
• Translation table: Assets/StreamingAssets/config/Localization.xlsx

Key classes and interfaces

Class	Role
LocalizationManager	Core module. Access via FF8.Local.
Localization components	Text, TextMeshPro, Font, Image, RawImage, SpriteRenderer, Material, Audio, Timeline

Supported component types

1. Text / TextMeshPro — with real-time ID display in editor
2. Font — font switching per language
3. Image / RawImage — localized images
4. SpriteRenderer — localized sprites
5. Material Renderer — localized materials
6. Audio Clips — localized audio
7. Timeline Tracks — localized timeline

API quick reference

// Change language
FF8.Local.ChangeLanguage("English");

// Get translated text (with format support)
string text = FF8.Local.GetTextFromId("test", "Support", "Format");
string text1 = FF8.Local.GetTextFromIdLanguage("test", "English");

// Language list and current language
var languages = FF8.Local.LanguageList;
string current = FF8.Local.CurrentLanguageName;

// Reload translation table
FF8.Local.Load();

// Refresh all localization components
FF8.Local.InjectAll();

Excel setup

1. Create Localization.xlsx in StreamingAssets/config/.
2. Rename the Sheet to LocalizedStrings.
3. Column layout: ID | Language1 | Language2 | ...
4. Supports 42 languages.
5. Alternative: use ExcelTool variant<name,variantName> for lightweight localization.

Workflow

1. Create Localization.xlsx with LocalizedStrings sheet.
2. Add localization components to UI elements (Text, Image, etc.).
3. Set ID references on components to match Excel IDs.
4. Call FF8.Local.ChangeLanguage() to switch languages.
5. Use F6 shortcut for quick switching in Editor.
6. For runtime content, use GetTextFromId() for text retrieval.
7. Call InjectAll() to refresh all components after language change (if not using components).
8. Use F6 in Editor for real-time language preview.

Common error handling

Error	Cause	Solution
Text shows ID instead of translation	ID not found in Excel	Check ID spelling in Excel table
Language not available	Missing column in Excel	Add language column to Localization.xlsx
Font rendering wrong	Font doesn't support target language	Use font that covers target language character set
Android Excel read fails	StreamingAssets access on Android	Use binary cache or SyncStreamingAssetsLoader

Cross-module dependencies

• ExcelTool: Translation tables use Excel infrastructure. Alternative: use ExcelTool variants.
• AssetManager: Localized assets (images, audio) loaded via AssetManager.
• UI: Localization components attach to UI elements.

Output checklist

• Translation Excel created with proper structure.
• Localization components attached to UI elements.
• Language switching tested.
• Validation status and remaining risks.