Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Changelog

## [1.3.1] - 2026-10-28

### Added
- **Load Table Method**: every table class gets `LoadTable()`, which loads the table for the selected locale
without blocking and returns `Task<StringTable>` / `Task<AssetTable>`. With **UniTask Members** there is also
`LoadTableAsync(CancellationToken)`. Asset table classes also get `LoadEntries()` / `LoadEntriesAsync`, which
load the table and the assets of all its entries. Off by default; turning it on never renames existing members.
- `LocalizedTables.LoadStringTable` / `LoadAssetTable` / `LoadAssetTableEntries` and
`LocalizedTablesUniTask.LoadStringTableAsync` / `LoadAssetTableAsync` / `LoadAssetTableEntriesAsync`.

## [1.3.0] - 2026-10-28

### Added
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ namespace Severnbli.LocalizationCodegen.Installer
public static partial class Installer
{
public const string PackageId = "com.severnbli.localization-codegen";
public const string Version = "1.3.0";
public const string Version = "1.3.1";

static Installer()
{
Expand Down
23 changes: 22 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ Add the scoped registry and the dependency to `Packages/manifest.json`:
}
],
"dependencies": {
"com.severnbli.localization-codegen": "1.3.0"
"com.severnbli.localization-codegen": "1.3.1"
}
}
```
Expand Down Expand Up @@ -318,6 +318,26 @@ title.StringChanged += text => label.text = text;

Asset entries use `LocalizedSprite`, `LocalizedAudioClip`, `LocalizedAsset<T>` and the other built-in localized asset types when available. Each access creates a new reference, so keep the one you subscribed to.

### Loading a table

Enable **Load Table Method** to give every table class a `LoadTable()` method that loads the table for the selected locale without blocking:

```csharp
public static Task<StringTable> LoadTable() => LocalizedTables.LoadStringTable(TableName);
```

```csharp
await Ui.LoadTable(); // e.g. behind a loading screen
label.text = Ui.HelloWorld; // the table is loaded, so this does not wait
```

- Asset table classes return `Task<AssetTable>`. `LoadTable()` loads only the table; each asset loads when it is requested.
- Asset table classes also get `LoadEntries()`, which loads the table and the assets of all its entries, so no asset lookup waits afterwards. Assets of a table whose **Preload Asset Table** metadata is **No Preload** are not loaded.
- With [UniTask Members](#unitask) there are also `LoadTableAsync(CancellationToken)` and, for asset tables, `LoadEntriesAsync(CancellationToken)`, returning `UniTask<StringTable>` / `UniTask<AssetTable>`.
- The table is loaded for the current locale. After a locale change, call it again to load the new locale's table.
- If Localization is not configured, the task completes with `null`.
- Turning the option on never renames existing members. A key named `LoadTable` or `LoadEntries` keeps its name, and the method gets a suffix (`LoadTable_2`). A table collection named `Task`, `StringTable` or `AssetTable` gets the `Table` class suffix.

### UniTask

Install [UniTask](https://github.com/Cysharp/UniTask) (`com.cysharp.unitask` 2.x) and enable **UniTask Members** to emit an awaitable variant next to every member:
Expand Down Expand Up @@ -360,6 +380,7 @@ Open **Project Settings > Localization Codegen**, or **Window > Localization Cod
| Smart Parameter Types | `Object` | `Object`, `Inferred` or [`Mapping`](#parameter-types). |
| Naming Convention | `Keep` | `Keep` or `PascalCase`. |
| Key Separators | empty | Characters that create nested classes, e.g. `/`. |
| Load Table Method | off | Emit [`LoadTable()`](#loading-a-table) on every table class, and `LoadEntries()` on asset table classes, to load without blocking. |
| UniTask Members | off | Also emit [`…Async` members](#unitask) returning `UniTask`. Requires UniTask. |
| Generate .asmdef | off | Write an assembly definition into the output folder, so the generated code gets its own assembly. |
| Fail CI On Smart String Mismatch | off | Make `CheckBatch` fail on locale placeholder mismatches. |
Expand Down
10 changes: 10 additions & 0 deletions Unity-Package/Assets/root/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Changelog

## [1.3.1] - 2026-10-28

### Added
- **Load Table Method**: every table class gets `LoadTable()`, which loads the table for the selected locale
without blocking and returns `Task<StringTable>` / `Task<AssetTable>`. With **UniTask Members** there is also
`LoadTableAsync(CancellationToken)`. Asset table classes also get `LoadEntries()` / `LoadEntriesAsync`, which
load the table and the assets of all its entries. Off by default; turning it on never renames existing members.
- `LocalizedTables.LoadStringTable` / `LoadAssetTable` / `LoadAssetTableEntries` and
`LocalizedTablesUniTask.LoadStringTableAsync` / `LoadAssetTableAsync` / `LoadAssetTableEntriesAsync`.

## [1.3.0] - 2026-10-28

### Added
Expand Down
78 changes: 78 additions & 0 deletions Unity-Package/Assets/root/Editor/CodeEmitter.cs
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ internal static class CodeEmitter
const string UniTaskType = "Cysharp.Threading.Tasks.UniTask";
const string CancellationTokenType = "System.Threading.CancellationToken";
const string DictionaryType = "System.Collections.Generic.Dictionary";
const string TaskType = "System.Threading.Tasks.Task";
const string StringTableType = "UnityEngine.Localization.Tables.StringTable";
const string AssetTableType = "UnityEngine.Localization.Tables.AssetTable";
const string CancellationTokenName = "cancellationToken";

/// <summary>
Expand All @@ -31,6 +34,12 @@ internal static class CodeEmitter
"UniTask", "CancellationToken", "Dictionary", "IEnumerable"
};

/// <summary>
/// Types only the <c>LoadTable</c> methods refer to. They are reserved only while the option is on, so turning
/// it on is the only thing that can rename a table class with one of these names.
/// </summary>
static readonly string[] s_LoadTableTypeNames = { "Task", "StringTable", "AssetTable" };

/// <summary>Assigns deterministic, collision-free class names to every model.</summary>
public static void AssignClassNames(IList<TableModel> models, EmitOptions options)
{
Expand Down Expand Up @@ -74,6 +83,8 @@ static HashSet<string> ReservedClassNames(IList<TableModel> models, EmitOptions

// Generated files refer to types by their simple names, which a table class must not hide.
set.UnionWith(s_ReferencedTypeNames);
if (options.LoadTable)
set.UnionWith(s_LoadTableTypeNames);
foreach (var model in models)
{
foreach (var entry in model.Entries)
Expand Down Expand Up @@ -106,6 +117,20 @@ public static string Emit(TableModel model, EmitOptions options)
root.ClassName = className;
AssignMemberNames(root, options);

// Claimed after every key's name, so turning the option on never renames an existing member.
if (options.LoadTable)
{
root.LoadTableName = CodegenText.Unique("LoadTable", root.MemberUsed);
if (model.IsAsset)
root.LoadEntriesName = CodegenText.Unique("LoadEntries", root.MemberUsed);
if (options.UniTask)
{
root.LoadTableAsyncName = CodegenText.Unique("LoadTableAsync", root.MemberUsed);
if (model.IsAsset)
root.LoadEntriesAsyncName = CodegenText.Unique("LoadEntriesAsync", root.MemberUsed);
}
}

var hasNamespace = !string.IsNullOrEmpty(options.Namespace);
var rootLevel = hasNamespace ? 1 : 0;

Expand Down Expand Up @@ -159,6 +184,10 @@ sealed class Scope
public readonly Dictionary<EntryModel, string> MemberNames = new Dictionary<EntryModel, string>();
public readonly Dictionary<EntryModel, string> AsyncMemberNames = new Dictionary<EntryModel, string>();
public readonly HashSet<string> MemberUsed = new HashSet<string>(StringComparer.Ordinal);
public string LoadTableName;
public string LoadTableAsyncName;
public string LoadEntriesName;
public string LoadEntriesAsyncName;
}

static Scope BuildScopeTree(TableModel model, EmitOptions options)
Expand Down Expand Up @@ -286,6 +315,9 @@ static void EmitScope(StringBuilder sb, Scope scope, TableModel model, EmitOptio
{
sb.Append(Indent(level + 1)).Append("public const string TableName = ")
.Append(CodegenText.Literal(model.Name)).Append(";\n");

if (scope.LoadTableName != null)
EmitLoadTable(sb, scope, model, options, types, level + 1);
}

var orderedEntries = scope.Entries
Expand Down Expand Up @@ -416,6 +448,52 @@ static void EmitAsyncEntry(StringBuilder sb, EntryModel entry, string name, Emit
sb.Append(tokenName).Append(");\n");
}

/// <summary>
/// Emits <c>LoadTable</c>, <c>LoadEntries</c> for asset tables, and their UniTask variants.
/// </summary>
static void EmitLoadTable(StringBuilder sb, Scope scope, TableModel model, EmitOptions options, TypeNames types, int level)
{
var table = types.Name(model.IsAsset ? AssetTableType : StringTableType);
var kind = model.IsAsset ? "Asset" : "String";
const string tableDoc = "Loads the table for the selected locale without blocking.";
const string entriesDoc = "Loads the table and the assets of all its entries for the selected locale without blocking.";

EmitLoadMethod(sb, scope.LoadTableName, "Load" + kind + "Table", table, tableDoc, options, types, level);
if (scope.LoadEntriesName != null)
EmitLoadMethod(sb, scope.LoadEntriesName, "LoadAssetTableEntries", table, entriesDoc, options, types, level);

if (scope.LoadTableAsyncName != null)
EmitLoadAsyncMethod(sb, scope.LoadTableAsyncName, "Load" + kind + "TableAsync", table, tableDoc, options, types, level);
if (scope.LoadEntriesAsyncName != null)
EmitLoadAsyncMethod(sb, scope.LoadEntriesAsyncName, "LoadAssetTableEntriesAsync", table, entriesDoc, options, types, level);
}

static void EmitLoadMethod(
StringBuilder sb, string name, string runtimeMethod, string table, string doc,
EmitOptions options, TypeNames types, int level)
{
sb.Append('\n');
if (options.XmlDocs)
sb.Append(Indent(level)).Append("/// <summary>").Append(doc).Append("</summary>\n");
sb.Append(Indent(level)).Append("public static ").Append(types.Name(TaskType)).Append('<').Append(table).Append("> ")
.Append(name).Append("() => ").Append(types.Name(EmitOptions.RuntimeTypeName))
.Append('.').Append(runtimeMethod).Append("(TableName);\n");
}

static void EmitLoadAsyncMethod(
StringBuilder sb, string name, string runtimeMethod, string table, string doc,
EmitOptions options, TypeNames types, int level)
{
sb.Append('\n');
if (options.XmlDocs)
sb.Append(Indent(level)).Append("/// <summary>").Append(doc).Append("</summary>\n");
sb.Append(Indent(level)).Append("public static ").Append(types.Name(UniTaskType)).Append('<').Append(table).Append("> ")
.Append(name).Append('(').Append(types.Name(CancellationTokenType)).Append(' ')
.Append(CancellationTokenName).Append(" = default)\n");
sb.Append(Indent(level)).Append(" => ").Append(types.Name(EmitOptions.UniTaskRuntimeTypeName))
.Append('.').Append(runtimeMethod).Append("(TableName, ").Append(CancellationTokenName).Append(");\n");
}

static void EmitRefClass(StringBuilder sb, TableModel model, EmitOptions options, TypeNames types, int level)
{
var strict = !string.IsNullOrEmpty(options.KeySeparators);
Expand Down
1 change: 1 addition & 0 deletions Unity-Package/Assets/root/Editor/CodeGenerator.cs
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,7 @@ static EmitOptions BuildEmitOptions(CodegenSettings settings)
GenerateAsmdef = settings.GenerateAsmdef,
// Generated code must compile, so the option only takes effect when the add-on is compiled.
UniTask = settings.GenerateUniTask && UniTaskSupport.IsAvailable,
LoadTable = settings.GenerateLoadTable,
TypeExists = LoadedTypeExists
};
}
Expand Down
7 changes: 5 additions & 2 deletions Unity-Package/Assets/root/Editor/CodegenModel.cs
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,9 @@ internal sealed class EmitOptions
/// <summary>When true, every member also gets a UniTask-returning <c>...Async</c> variant.</summary>
public bool UniTask;

/// <summary>When true, every table class gets a <c>LoadTable</c> method (and <c>LoadTableAsync</c> with UniTask).</summary>
public bool LoadTable;

/// <summary>
/// Optional check whether a namespace (empty for the global namespace) contains a type with the given simple
/// name. Generated files keep a type <c>global::</c> qualified when its simple name could bind to another type.
Expand All @@ -107,8 +110,8 @@ internal sealed class EmitOptions
/// <summary>Stable signature of every option that can change output.</summary>
public string Signature()
{
// UniTask is appended only when enabled, so existing hashes (and files) stay valid after upgrading.
return (UniTask ? "unitask|" : "") + string.Join("|", new[]
// UniTask and LoadTable are added only when enabled, so existing hashes (and files) stay valid after upgrading.
return (LoadTable ? "loadtable|" : "") + (UniTask ? "unitask|" : "") + string.Join("|", new[]
{
Namespace ?? "<global>",
"usings",
Expand Down
4 changes: 4 additions & 0 deletions Unity-Package/Assets/root/Editor/CodegenSettings.cs
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ public sealed class CodegenSettings : ScriptableSingleton<CodegenSettings>
// Options introduced in 1.2.0. Off by default, so no migration is needed.
[SerializeField] private bool generateUniTask;

// Options introduced in 1.3.1. Off by default, so no migration is needed.
[SerializeField] private bool generateLoadTable;

public bool SetupCompleted { get => setupCompleted; set => setupCompleted = value; }
public string OutputFolder { get => outputFolder; set => outputFolder = value; }
public string Namespace { get => generatedNamespace; set => generatedNamespace = value; }
Expand All @@ -58,6 +61,7 @@ public sealed class CodegenSettings : ScriptableSingleton<CodegenSettings>
public bool GenerateAsmdef { get => generateAsmdef; set => generateAsmdef = value; }
public bool FailOnSmartStringMismatch { get => failOnSmartStringMismatch; set => failOnSmartStringMismatch = value; }
public bool GenerateUniTask { get => generateUniTask; set => generateUniTask = value; }
public bool GenerateLoadTable { get => generateLoadTable; set => generateLoadTable = value; }

public SmartStringMode SmartStrings
{
Expand Down
3 changes: 3 additions & 0 deletions Unity-Package/Assets/root/Editor/SettingsGui.cs
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ internal static class Content
"Emit a nested Ref class with LocalizedString / LocalizedAsset references that follow locale changes.");
public static readonly GUIContent UniTask = new GUIContent("UniTask Members",
"Also emit ...Async members that return UniTask and accept a CancellationToken. Requires UniTask (com.cysharp.unitask).");
public static readonly GUIContent LoadTable = new GUIContent("Load Table Method",
"Emit LoadTable() on every table class and LoadEntries() on asset table classes to load without blocking (and ...Async variants with UniTask Members).");
public static readonly GUIContent XmlDocs = new GUIContent("XML Documentation",
"Emit XML doc comments containing the default locale text.");

Expand Down Expand Up @@ -360,6 +362,7 @@ static void DrawMembers(CodegenSettings s)
s.GenerateReferences = value;
}

s.GenerateLoadTable = EditorGUILayout.Toggle(Content.LoadTable, s.GenerateLoadTable);
s.GenerateUniTask = EditorGUILayout.Toggle(Content.UniTask, s.GenerateUniTask);
if (s.GenerateUniTask && !UniTaskSupport.IsAvailable)
EditorGUILayout.HelpBox(UniTaskSupport.MissingMessage, MessageType.Warning);
Expand Down
23 changes: 22 additions & 1 deletion Unity-Package/Assets/root/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ Add the scoped registry and the dependency to `Packages/manifest.json`:
}
],
"dependencies": {
"com.severnbli.localization-codegen": "1.3.0"
"com.severnbli.localization-codegen": "1.3.1"
}
}
```
Expand Down Expand Up @@ -318,6 +318,26 @@ title.StringChanged += text => label.text = text;

Asset entries use `LocalizedSprite`, `LocalizedAudioClip`, `LocalizedAsset<T>` and the other built-in localized asset types when available. Each access creates a new reference, so keep the one you subscribed to.

### Loading a table

Enable **Load Table Method** to give every table class a `LoadTable()` method that loads the table for the selected locale without blocking:

```csharp
public static Task<StringTable> LoadTable() => LocalizedTables.LoadStringTable(TableName);
```

```csharp
await Ui.LoadTable(); // e.g. behind a loading screen
label.text = Ui.HelloWorld; // the table is loaded, so this does not wait
```

- Asset table classes return `Task<AssetTable>`. `LoadTable()` loads only the table; each asset loads when it is requested.
- Asset table classes also get `LoadEntries()`, which loads the table and the assets of all its entries, so no asset lookup waits afterwards. Assets of a table whose **Preload Asset Table** metadata is **No Preload** are not loaded.
- With [UniTask Members](#unitask) there are also `LoadTableAsync(CancellationToken)` and, for asset tables, `LoadEntriesAsync(CancellationToken)`, returning `UniTask<StringTable>` / `UniTask<AssetTable>`.
- The table is loaded for the current locale. After a locale change, call it again to load the new locale's table.
- If Localization is not configured, the task completes with `null`.
- Turning the option on never renames existing members. A key named `LoadTable` or `LoadEntries` keeps its name, and the method gets a suffix (`LoadTable_2`). A table collection named `Task`, `StringTable` or `AssetTable` gets the `Table` class suffix.

### UniTask

Install [UniTask](https://github.com/Cysharp/UniTask) (`com.cysharp.unitask` 2.x) and enable **UniTask Members** to emit an awaitable variant next to every member:
Expand Down Expand Up @@ -360,6 +380,7 @@ Open **Project Settings > Localization Codegen**, or **Window > Localization Cod
| Smart Parameter Types | `Object` | `Object`, `Inferred` or [`Mapping`](#parameter-types). |
| Naming Convention | `Keep` | `Keep` or `PascalCase`. |
| Key Separators | empty | Characters that create nested classes, e.g. `/`. |
| Load Table Method | off | Emit [`LoadTable()`](#loading-a-table) on every table class, and `LoadEntries()` on asset table classes, to load without blocking. |
| UniTask Members | off | Also emit [`…Async` members](#unitask) returning `UniTask`. Requires UniTask. |
| Generate .asmdef | off | Write an assembly definition into the output folder, so the generated code gets its own assembly. |
| Fail CI On Smart String Mismatch | off | Make `CheckBatch` fail on locale placeholder mismatches. |
Expand Down
Loading
Loading