Data file tables

Understand how table collections ship and load as data files instead of assets.

With a data-file source, a collection’s tables ship in the build as plain files, one per locale, instead of serialized assets. Translators can read and edit the files, you can patch a build without a rebuild, and you can add a language with a new file. The built-in format is JSON (JsonResourceProvider).

You can also create your own data-file source for custom file formats. Refer to Create a file table provider for text files.

Files and naming

Each table becomes one file named [collection-name]_[locale-code].[extension], for example Menus_fr.json. In a build, the files sit in StreamingAssets/{SubPath}. SubPath defaults to LocalizationTables, and you can change it on the source in the Localization settings.

From authoring to runtime

flowchart TD
    author["Author tables in the Editor<br>(regular collection assets)"]
    gen["File generation<br>writes {collection}_{locale}.json to the project Library"]
    build["Player build<br>copies the files into StreamingAssets/SubPath"]
    run["Runtime<br>reads the file and rebuilds the table in memory"]
    graft["Entries a file can't carry<br>ship in a baked table asset and graft in at load"]

    author --> gen
    gen --> build
    build --> run
    graft --> run

    classDef code fill:#F5F5F5,stroke:#BDBDBD,color:#111;
    class author,gen,build,run,graft code;
    linkStyle default stroke:#2196F3,stroke-width:1.5px;

You author the collection in the Resource Tables window. The files are an export the build produces, not something you edit in the project. At build time, Unity generates the files into the project’s Library folder and stages them into StreamingAssets. At runtime, the source reads a table’s file the first time it needs the table and rebuilds it in memory.

The file preserves string values and plain-data entries. Some entries can’t ship in a file: direct object references, and entries flagged Exclude entry from player export. Unity ships these entries in a baked table asset and merges them into the file-built table at load time. The build log lists which tables kept entries in the baked asset.

Test in Play mode

Each data-file source has a Play Mode Source option in its section of the Localization settings. This option controls what Play mode uses:

Platform behavior

File reads need direct file access to StreamingAssets. On Android and Web, StreamingAssets is a URL. On these platforms, Localization fetches the files with a web request and skips locale discovery, so you can’t add languages after release this way. Refer to Add a language to a built Player.

Custom file formats

The JSON data-file source consists of scripts to read and write the files, along with a FileTableProvider. To ship tables in your own format instead of JSON, refer to Create a file table provider for text files.

Additional resources

• Add a language to a built Player
• Create a file table provider for text files
• Content sources