Content sources

Understand how content source providers store and load table collections and their assets.

A content source decides how the project stores localized content, how it ships in a build, and how it loads at runtime. Each table collection is assigned to one source. In the API, sources are IAssetProvider implementations that return the requested localized content, and they live in the Localization settings as an ordered list.

The source chain

flowchart TD
    req["Request: table or asset by address"]
    chain["AssetProvider chain"]
    p1["Direct references<br>(ReferencedAssetProvider)"]
    p2["Resources folder<br>(ResourceFolderProvider)"]
    p3["Data files (JSON)<br>(JsonResourceProvider)"]
    val["First source that serves the address wins"]

    req --> chain
    chain --> p1
    chain --> p2
    chain --> p3
    p1 --> val
    p2 --> val
    p3 --> val

    classDef code fill:#F5F5F5,stroke:#BDBDBD,color:#111;
    class req,chain,p1,p2,p3,val code;
    linkStyle default stroke:#2196F3,stroke-width:1.5px;

The Localization settings hold an ordered list of sources (AssetProvider). A request walks the list until a source serves it. The list allows one source of each type, and Default for new collections controls which source Unity assigns a new collection to.

Built-in sources

Localization provides the following content sources. You can enable them by adding them to your Content sources list in the Localization settings reference.

Note: Everything under a Resources folder is included with the build, including tables for disabled locales. The settings page warns when this applies.

How Unity assigns a source to a collection

Each collection records the source that serves it. For most sources, the collection asset’s Inspector window shows a source dropdown, and changing the dropdown re-registers the collection’s tables with the new source in one undo step. No files move on disk.

The Resources folder source is different: membership follows the collection’s location, so the source dropdown doesn’t include it. A collection saved under a Resources folder belongs to this source, and moving the assets out of Resources moves it off. Unity re-registers the collection whenever the assets move.

A collection’s assignment and location can disagree, for example a collection under Resources that’s assigned to another source. When this happens, the collection’s Inspector window shows a warning with a button that fixes the assignment.

Asset entries and sources

String entries live in the table, so the source only affects how Unity stores the table itself. For asset entries, you also need to decide how Unity stores each asset. That decision is per entry, not per source. A Direct entry references the asset, and a Resources entry stores a path. Refer to Localize assets.

Custom sources

Content that lives somewhere the built-in sources can’t reach, for example downloaded content or a mod folder, needs a custom source. A custom source is a runtime IAssetProvider that supports one or both loading paths (IAsyncAssetProvider, ISynchronousAssetProvider), paired with an Editor companion that registers collection content with the provider when you assign a collection to it. Requests arrive as an AssetKey that carries the address and expected type.

For a complete example, refer to Create a custom asset provider. To add a custom table file format instead, refer to Create a file table provider for text files.

Additional resources

• Data file tables
• Localize assets
• Create a custom asset provider