Search documentation of Localize

# Localize.Locale.Provider.Cache (Localize v0.39.0)

Copy Markdown View Source

On-disk cache for downloaded locale data files.

This module is responsible for reading and writing locale ETF files under the directory returned by `Localize.Locale.Provider.locale_cache_dir/0`, and for detecting when a cached file is stale relative to `Localize.version/0`.

## Primary API

- `get/1` — returns cached locale data, or an error tuple if the file is missing or stale.

- `store/2` — writes locale data to the cache directory.

- `stale?/1` — checks whether a cached locale file is stale.

- `path/1` — returns the absolute path for a locale's cache file.

## Summary

### Types

locale_id()

A locale identifier as an atom.

### Functions

get(locale_id)

Retrieves locale data from the cache directory.

path(locale_id)

Returns the absolute cache file path for the given locale.

stale?(locale_id)

Returns whether a cached locale file is stale.

store(locale_id, content)

Stores locale content in the cache directory.

## Types

# locale_id()

    @type locale_id() :: atom()

A locale identifier as an atom.

## Functions

# get(locale_id)

    @spec get(locale_id()) :: {:ok, map()} | {:error, Exception.t()}

Retrieves locale data from the cache directory.

Reads the locale's cache file, decodes it, and validates that its `:version` field matches `Localize.version/0`.

### Arguments

- `locale_id` is a locale identifier atom.

### Returns

- `{:ok, locale_data}` if the cache file is present and its version matches the current version.

- `{:error, Localize.LocaleIsStaleError.t()}` if the cache file is present but its version does not match.

- `{:error, Localize.LocaleNotFoundInCacheError.t()}` if the cache file is not present.

# path(locale_id)

    @spec path(locale_id()) :: String.t()

Returns the absolute cache file path for the given locale.

### Arguments

- `locale_id` is a locale identifier atom.

### Returns

- A string path to the locale's cache file.

### Examples

    iex> path = Localize.Locale.Provider.Cache.path(:en)
    iex> String.ends_with?(path, "en.etf")
    true

# stale?(locale_id)

    @spec stale?(locale_id()) :: boolean()

Returns whether a cached locale file is stale.

A cache file is considered stale if its `:version` field does not equal `Localize.version/0`. A file that is missing or unreadable is also considered stale.

### Arguments

- `locale_id` is a locale identifier atom.

### Returns

- `true` if the cache file is missing, unreadable, or its version does not match `Localize.version/0`.

- `false` if the cache file is present and its version matches.

# store(locale_id, content)

    @spec store(locale_id(), binary()) :: {:ok, String.t()} | {:error, Exception.t()}

Stores locale content in the cache directory.

Creates the cache directory if it does not already exist and writes `content` to the locale's cache file. `content` should be the raw binary form of the locale ETF file.

### Arguments

- `locale_id` is a locale identifier atom.

- `content` is a binary containing the encoded locale data.

### Returns

- `{:ok, path}` where `path` is the absolute path the content was written to.

- `{:error, Localize.LocaleCacheWriteError.t()}` on failure.