Negotiate Locale

localization.locale_negotiate

ProductionEngine wrapper (Class A)Deterministicstrictfastv1.0.0

No network

Overview

You send the locales you can serve and either an ordered requestedLocales list with quality values or a single acceptLanguage string, never both. LOOKUP walks each requested tag by dropping subtags. BEST_FIT uses ICU locale matching. A range with q=0 is skipped. defaultLocale is used only when nothing matches and must itself be available. We do not guess from an IP address or from content. A successful call costs 1 execution credit.

Agents guess Accept-Language matching. RFC 4647 lookup and ICU best-fit are mechanical, versioned answers.

Reliability

Same lists, same strategy, same ICU version, same answer. LOCALE_INVALID — trigger: an available or requested tag is POSIX or ill-formed; retryable: no; next: send hyphenated BCP 47 tags. ACCEPT_LANGUAGE_INVALID — trigger: the header cannot be parsed; retryable: no; next: send a standard Accept-Language value. REQUEST_SHAPE_INVALID — trigger: both or neither of requestedLocales and acceptLanguage; retryable: no; next: send exactly one. DEFAULT_LOCALE_UNAVAILABLE — trigger: defaultLocale is not in availableLocales; retryable: no; next: add it to the available list. ITEM_LIMIT_EXCEEDED — trigger: more than 500 available locales; retryable: no; next: shrink the list.

Context footprint

Short locale lists in. A successful call costs 1 execution credit.

When to use it

When you hold the locales you ship and a request list or Accept-Language header.

When you only need to canonicalize one tag, or to detect language from text.

Scope

Note

Selects one available locale from an ordered request or an Accept-Language value using LOOKUP or BEST_FIT.

Non-goals

Does not detect language from content
Does not look up a locale from an IP address or user profile
Does not return a ranked list of resources

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

normalization

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input64 KB

How we handle your data

Sensitive input, safe output

What this means

This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response does not contain submitted content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
requestedLocales	array	No	From 1 through 50 closed requested ranges in caller order, later sorted by q then order. Omit it when acceptLanguage is sent.
acceptLanguage	string	No	One HTTP Accept-Language header value. Omit it when requestedLocales is sent.
availableLocales	array	Yes	From 1 through 501 available locales you can serve; 501 hits ITEM_LIMIT_EXCEEDED.
strategy	string	No	LOOKUP walks by dropping subtags; BEST_FIT uses ICU matching. Omit it for LOOKUP.
defaultLocale	string	No	Fallback tag that must be available; omit it and a miss omits selected.

Output schema

Field	Type	Required	Description
selected	string	No	Chosen canonical tag; omit it when nothing matched.
matchedRequest	string	No	Requested range that produced the match; omit it when the default applied.
quality	number	No	q-value of the matched request; omit it when the default applied.
strategy	string	Yes	LOOKUP or BEST_FIT as actually applied for this negotiation.
fallbackChain	array	Yes	From 0 through 32 tags tried in order; empty when nothing was attempted.
_meta	object	Yes	Closed ICU and CLDR versions used for this answer, with icuVersion and cldrVersion strings.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"localization.locale_negotiate","input":{"requestedLocales":[{"locale":"fr-CA","q":1}],"availableLocales":["fr","en"],"strategy":"LOOKUP"}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("localization.locale_negotiate", {"requestedLocales":[{"locale":"fr-CA","q":1}],"strategy":"LOOKUP","availableLocales":["fr","en"]});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
LOCALE_INVALID	400	No	The request payload failed this skill's input validation.
ACCEPT_LANGUAGE_INVALID	400	No	The request payload failed this skill's input validation.
REQUEST_SHAPE_INVALID	400	No	The request payload failed this skill's input validation.
DEFAULT_LOCALE_UNAVAILABLE	400	No	The request payload failed this skill's input validation.
ITEM_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not detect language from content
Does not look up a locale from an IP address or user profile
Does not return a ranked list of resources
Guessing language from a paragraph of source text
Canonicalizing a single tag you already hold

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "localization.locale_negotiate",
  "input": {
    "requestedLocales": [
      {
        "locale": "fr-CA",
        "q": 1
      }
    ],
    "strategy": "LOOKUP",
    "availableLocales": [
      "fr",
      "en"
    ]
  }
}

Examples

Region fallback with lookup

Inputjson

{
  "requestedLocales": [
    {
      "locale": "fr-CA",
      "q": 1
    }
  ],
  "strategy": "LOOKUP",
  "availableLocales": [
    "fr",
    "en"
  ]
}

Expected outputjson

{
  "_meta": {
    "icuVersion": "76.1",
    "cldrVersion": "46.0"
  },
  "selected": "fr",
  "matchedRequest": "fr-CA",
  "strategy": "LOOKUP",
  "fallbackChain": [
    "fr-CA",
    "fr"
  ],
  "quality": 1
}

Tip

LOOKUP drops CA and selects fr

Accept-Language with q zero