# spotify/java-locales architecture

> Architecture diagram of the GitHub repository spotify/java-locales, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spotify/java-locales
- Repository: https://github.com/spotify/java-locales

## Overview

Java Locales is a library for locale negotiation, locale affinity, and Unicode locale utilities. Its main workflow is to provide supported locales and resolve the best matching translation and formatting locales for an application-defined context; the README also documents audience-specific locale lists. Separate affinity operations compare one locale against a configured set or compare two locales. The graph reflects README-documented capabilities and relationships only; no source excerpts were provided, so internal calls and implementation details are not asserted.

Main entry points: [`locales-common/src/main/java/com/spotify/i18n/locales/common/LocalesResolver.java`](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocalesResolver.java) (Locale resolution), [`locales-common/src/main/java/com/spotify/i18n/locales/common/SupportedLocalesSupplier.java`](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/SupportedLocalesSupplier.java) (Supported locales), [`locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedSupportedLocalesSupplier.java`](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedSupportedLocalesSupplier.java) (Audience locales), [`locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityCalculator.java`](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityCalculator.java) (Set affinity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_negotiation["Locale negotiation"]
  node_supported["Supported locales"]
  node_audience["Audience locales"]
  node_resolver["Locale resolution"]
  node_context["Resolution context"]
end

subgraph group_affinity["Locale affinity"]
  node_affinity_set["Set affinity"]
  node_affinity_pair["Pair affinity"]
end

subgraph group_utilities["Locale utilities"]
  node_accept_language["Accept-Language"]
  node_available["Available locales"]
  node_language["Language lookup<br/>[LanguageUtils.java]"]
  node_language_tag["Language tags"]
  node_hierarchy["Locale hierarchy"]
end

subgraph group_domain["Domain model"]
  node_resolved["Resolved locale"]
  node_affinity_model["Affinity result"]
end

node_caller(("Application caller"))

node_caller -->|"requests locales"| node_supported
node_caller -->|"selects audience"| node_audience
node_caller -->|"requests resolution"| node_resolver
node_supported -->|"provides candidates"| node_resolver
node_audience -->|"provides candidates"| node_resolver
node_caller -->|"compares locale"| node_affinity_set
node_caller -->|"compares locales"| node_affinity_pair
node_caller -->|"parses header"| node_accept_language
node_caller -->|"retrieves locales"| node_available
node_caller -->|"looks up language"| node_language
node_caller -->|"normalizes tags"| node_language_tag
node_caller -->|"navigates hierarchy"| node_hierarchy
node_resolver -.->|"selects locales"| node_resolved
node_affinity_set -.->|"returns affinity"| node_affinity_model
node_affinity_pair -.->|"returns affinity"| node_affinity_model

click node_supported "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/SupportedLocalesSupplier.java"
click node_audience "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedSupportedLocalesSupplier.java"
click node_resolver "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocalesResolver.java"
click node_context "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedLocalesResolver.java"
click node_affinity_set "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityCalculator.java"
click node_affinity_pair "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityBiCalculator.java"
click node_accept_language "https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/acceptlanguage/AcceptLanguageUtils.java"
click node_available "https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/available/AvailableLocalesUtils.java"
click node_language "https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/language/LanguageUtils.java"
click node_language_tag "https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/languagetag/LanguageTagUtils.java"
click node_hierarchy "https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/hierarchy/LocalesHierarchyUtils.java"
click node_resolved "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/model/ResolvedLocale.java"
click node_affinity_model "https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/model/LocaleAffinityResult.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_supported,node_audience,node_resolver,node_context toneBlue
class node_affinity_set,node_affinity_pair toneAmber
class node_accept_language,node_available,node_language,node_language_tag,node_hierarchy toneMint
class node_resolved,node_affinity_model toneRose
class node_caller toneIndigo
```

## Components

### Locale negotiation

- [Supported locales](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/SupportedLocalesSupplier.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/SupportedLocalesSupplier.java`
- [Audience locales](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedSupportedLocalesSupplier.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedSupportedLocalesSupplier.java`
- [Locale resolution](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocalesResolver.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/LocalesResolver.java`
- [Resolution context](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedLocalesResolver.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/ContextBasedLocalesResolver.java`

### Locale affinity

- [Set affinity](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityCalculator.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityCalculator.java`
- [Pair affinity](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityBiCalculator.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/LocaleAffinityBiCalculator.java`

### Locale utilities

- [Accept-Language](https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/acceptlanguage/AcceptLanguageUtils.java): `locales-utils/src/main/java/com/spotify/i18n/locales/utils/acceptlanguage/AcceptLanguageUtils.java`
- [Available locales](https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/available/AvailableLocalesUtils.java): `locales-utils/src/main/java/com/spotify/i18n/locales/utils/available/AvailableLocalesUtils.java`
- [Language lookup](https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/language/LanguageUtils.java): `locales-utils/src/main/java/com/spotify/i18n/locales/utils/language/LanguageUtils.java`
- [Language tags](https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/languagetag/LanguageTagUtils.java): `locales-utils/src/main/java/com/spotify/i18n/locales/utils/languagetag/LanguageTagUtils.java`
- [Locale hierarchy](https://github.com/spotify/java-locales/blob/main/locales-utils/src/main/java/com/spotify/i18n/locales/utils/hierarchy/LocalesHierarchyUtils.java): `locales-utils/src/main/java/com/spotify/i18n/locales/utils/hierarchy/LocalesHierarchyUtils.java`

### Domain model

- [Resolved locale](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/model/ResolvedLocale.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/model/ResolvedLocale.java`
- [Affinity result](https://github.com/spotify/java-locales/blob/main/locales-common/src/main/java/com/spotify/i18n/locales/common/model/LocaleAffinityResult.java): `locales-common/src/main/java/com/spotify/i18n/locales/common/model/LocaleAffinityResult.java`

### Other components

- **Application caller**

## Connections

- Application caller → Supported locales: requests locales (evidence: `README.md`)
- Application caller → Audience locales: selects audience (evidence: `README.md`)
- Application caller → Locale resolution: requests resolution (evidence: `README.md`)
- Supported locales → Locale resolution: provides candidates (evidence: `README.md`)
- Audience locales → Locale resolution: provides candidates (evidence: `README.md`)
- Application caller → Set affinity: compares locale (evidence: `README.md`)
- Application caller → Pair affinity: compares locales (evidence: `README.md`)
- Application caller → Accept-Language: parses header (evidence: `README.md`)
- Application caller → Available locales: retrieves locales (evidence: `README.md`)
- Application caller → Language lookup: looks up language (evidence: `README.md`)
- Application caller → Language tags: normalizes tags (evidence: `README.md`)
- Application caller → Locale hierarchy: navigates hierarchy (evidence: `README.md`)
- Locale resolution → Resolved locale: selects locales
- Set affinity → Affinity result: returns affinity
- Pair affinity → Affinity result: returns affinity
