Localization
Sphere follows a strict localization pattern: the backend always returns translation keys and codes, never translated labels. The frontend is responsible for translating these codes using the user's effective locale. Dates are always transmitted in ISO 8601 UTC format.
Localization model
The localization system uses a cascade to determine the effective locale for each user:
- User locale -- if the user has explicitly set a preferred locale
- Tenant locale -- the default locale configured for the tenant
- Platform default -- falls back to
en_US
The backend never returns translated strings in API responses. Fields like status, priority, and type contain translation key codes (e.g., status.active). The frontend maps these to the appropriate translated label using the user's effective locale.
List supported locales
Retrieve the list of all supported locales on the platform. This is a public endpoint that does not require authentication. Use it to populate locale selection dropdowns in registration or settings forms.
Request
curl https://your-sphere.example.com/core/api/v1/locales
Response
{
"data": [
{
"code": "en_US",
"name": "English (US)",
"direction": "ltr"
},
{
"code": "fr_FR",
"name": "French (France)",
"direction": "ltr"
},
{
"code": "ar_SA",
"name": "Arabic (Saudi Arabia)",
"direction": "rtl"
},
{
"code": "de_DE",
"name": "German (Germany)",
"direction": "ltr"
}
]
}
Get effective locale
Retrieve the effective locale for the currently authenticated user. The response indicates both the resolved locale and the source of the resolution (user preference, tenant default, or platform default).
This endpoint requires authentication.
Request
curl https://your-sphere.example.com/core/api/v1/locale \
-H "Authorization: Bearer {access_token}"
Response
{
"data": {
"locale": "fr_FR",
"source": "user"
}
}
Response (tenant fallback)
{
"data": {
"locale": "en_US",
"source": "tenant"
}
}
Validate locale
Validate whether a given locale code is supported by the platform. This is a public endpoint that does not require authentication. Use it to verify a locale before setting it on a user profile.
Required attributes
- Name
locale- Type
- string
- Description
The locale code to validate (e.g.,
fr_FR,en_US).
Request
curl -X POST https://your-sphere.example.com/core/api/v1/locale/validate \
-H "Content-Type: application/json" \
-d '{"locale": "fr_FR"}'
Response (valid)
{
"data": {
"locale": "fr_FR",
"valid": true
}
}
Response (invalid)
{
"data": {
"locale": "xx_XX",
"valid": false
}
}
List timezones
Retrieve the list of all supported timezones. This is a public endpoint that does not require authentication. Use it to populate timezone selection dropdowns.
Request
curl https://your-sphere.example.com/core/api/v1/timezones
Response
{
"data": [
"UTC",
"Europe/Paris",
"Europe/London",
"America/New_York",
"America/Los_Angeles",
"Asia/Tokyo",
"Asia/Dubai",
"Africa/Tunis"
]
}
List translation key categories
Retrieve all translation key categories and their keys. This is a public endpoint that does not require authentication. Use it to build the frontend translation mapping between key codes and localized labels.
Categories group related translation keys (e.g., all status codes, all priority levels, all action types). The backend returns these key codes in API responses, and the frontend maps them to human-readable labels based on the user's locale.
Request
curl https://your-sphere.example.com/core/api/v1/translation-keys
Response
{
"data": {
"categories": [
"status",
"priority",
"action",
"entity_type",
"role"
],
"keys": {
"status": [
"status.active",
"status.inactive",
"status.pending",
"status.archived"
],
"priority": [
"priority.low",
"priority.medium",
"priority.high",
"priority.urgent"
],
"action": [
"action.create",
"action.update",
"action.delete",
"action.assign"
]
}
}
}
Get translation keys by category
Retrieve all translation keys for a specific category. This is a public endpoint that does not require authentication.
Path parameters
- Name
category- Type
- string
- Description
The category of translation keys to retrieve (e.g.,
status,priority,action).
Request
curl https://your-sphere.example.com/core/api/v1/translation-keys/status
Response
{
"data": {
"category": "status",
"keys": [
"status.active",
"status.inactive",
"status.pending",
"status.archived",
"status.draft",
"status.published"
]
}
}