dachshund/strategy

Strategies for detecting the user’s preferred locale.

Dachshund evaluates strategies in order, using the first successful result. This allows fallback chains like: cookie → URL → browser language → default.

Basic Usage

import dachshund/strategy
import dachshund/locale

// Create a custom strategy chain
let my_strategy = [
  strategy.cookie("locale"),
  strategy.preferred_language(),
  strategy.base_locale(locale.En),
]

// Evaluate to get the user's locale
strategy.evaluate(my_strategy, locale.En)
// -> StrategyResult(locale: En, source: "baseLocale")

Pre-built Strategies

Dachshund provides common strategy combinations:

default_strategy - URL or default
user_preference_strategy - User saved preference, then URL, then browser, then default
auto_detect_strategy - Auto-detect from multiple sources

Types

Strategy

</>

A locale detection strategy.

Strategies are evaluated in order until one succeeds. Each strategy type checks a different source for locale information.

pub type Strategy {
  Cookie(String)
  LocalStorage(String)
  Url(UrlPattern)
  PreferredLanguage
  BaseLocale(locale.Locale)
  DocumentLang
}

Constructors

```
Cookie(String)
```
Check a cookie for the locale value. The cookie should contain a locale code like "en" or "de".
```
LocalStorage(String)
```
Check localStorage for the locale value. The key should contain a locale code like "en" or "de".
```
Url(UrlPattern)
```
Extract locale from the URL path (e.g., /en/, /de/products). Uses the first path segment after the domain.
```
PreferredLanguage
```
Use the browser’s language preferences from navigator.languages.
```
BaseLocale(locale.Locale)
```
Always return a fixed locale as the final fallback.
```
DocumentLang
```
Use the lang attribute from the <html> document element.

StrategyResult

</>

The result of evaluating a strategy chain.

Contains the detected locale and which strategy provided it.

pub type StrategyResult {
  StrategyResult(locale: locale.Locale, source: String)
}

Constructors

StrategyResult(locale: locale.Locale, source: String)

UrlPattern

</>

Configuration for URL-based locale detection.

Defines which locales are valid in the URL and what to use as fallback.

pub type UrlPattern {
  UrlPattern(
    locales: List(locale.Locale),
    base_locale: locale.Locale,
    prefix: String,
  )
}

Constructors

UrlPattern(
  locales: List(locale.Locale),
  base_locale: locale.Locale,
  prefix: String,
)

Values

auto_detect_strategy

</>

pub const auto_detect_strategy: List(Strategy)

Auto-detect strategy that checks multiple sources.

Check order: localStorage → browser language → URL → English

base_locale

</>

pub fn base_locale(base: locale.Locale) -> Strategy

Create a fixed fallback locale strategy.

Use as the last strategy in your chain to ensure a locale is always returned.

Example

strategy.base_locale(locale.En)

</>

pub fn cookie(name: String) -> Strategy

Create a cookie-based strategy.

The cookie value should be a locale code like "en" or "de".

Example

strategy.cookie("myapp_locale")

default_strategy

</>

pub const default_strategy: List(Strategy)

Default strategy: check URL, then fall back to English.

Use this for simple apps that only need URL-based locale detection.

document_lang

</>

pub fn document_lang() -> Strategy

Create a document language strategy.

Uses the lang attribute from the <html> element.

Example

strategy.document_lang()

evaluate

</>

pub fn evaluate(
  strategies: List(Strategy),
  fallback: locale.Locale,
) -> StrategyResult

Evaluate a strategy chain to detect the user’s locale.

Strategies are checked in order. The first one that returns a valid locale is used. If all strategies fail, the fallback locale is returned.

Example

let strategies = [
  strategy.cookie("locale"),
  strategy.preferred_language(),
  strategy.base_locale(locale.En),
]

strategy.evaluate(strategies, locale.En)
// -> StrategyResult(locale: En, source: "baseLocale")

local_storage

</>

pub fn local_storage(key: String) -> Strategy

Create a localStorage-based strategy.

The stored value should be a locale code like "en" or "de".

Example

strategy.local_storage("locale")

preferred_language

</>

pub fn preferred_language() -> Strategy

Create a browser language preference strategy.

Uses navigator.languages to get the user’s preferred languages and selects the first one that Dachshund supports.

Example

strategy.preferred_language()

url

</>

pub fn url(
  locales: List(locale.Locale),
  base_locale: locale.Locale,
) -> Strategy

Create a URL-based strategy for path locales.

Extracts locale from the URL path (e.g., /en/, /de/about). Uses the first path segment after the domain.

Example

// Matches /en/, /de/, /fr/ in the URL
strategy.url([locale.En, locale.De, locale.Fr], locale.En)

url_pattern

</>

pub fn url_pattern(
  locales locales: List(locale.Locale),
  base_locale base_locale: locale.Locale,
  prefix prefix: String,
) -> UrlPattern

Create a URL pattern configuration.

Parameters

locales: List of supported locales to match in URLs
base_locale: Fallback locale when URL doesn’t contain a locale
prefix: Optional prefix before the locale in URL (e.g., "lang")

url_patterns_for

</>

pub fn url_patterns_for(
  locales: List(locale.Locale),
) -> UrlPattern

Create a URL pattern from a list of locales.

The first locale in the list is used as the base locale.

Example

strategy.url_patterns_for([locale.En, locale.De, locale.Fr])
// -> UrlPattern(locales: [En, De, Fr], base_locale: En, prefix: "")

url_with_prefix

</>

pub fn url_with_prefix(
  locales: List(locale.Locale),
  base_locale: locale.Locale,
  prefix: String,
) -> Strategy

Create a URL-based strategy with a prefix.

Example

// Matches /lang/en/, /lang/de/ in the URL
strategy.url_with_prefix([locale.En, locale.De], locale.En, "lang")

user_preference_strategy

</>

pub const user_preference_strategy: List(Strategy)

Strategy that prioritizes user preference saved in localStorage.

Check order: localStorage → URL → browser language → English