Add localized rows to a dataset

datasets.localize(, ) -> DatasetLocalizeResponse

POST/api/v1/datasets/{dataset_id}/localize

Adapts a sample of this dataset’s rows to each country/language pair — translating the text and matching that country’s conventions — and returns the result as a new dataset, leaving this one unchanged. The new dataset carries this dataset’s rows alongside the localized ones. Poll GET /datasets/{dataset_id}/status on the returned id until it reaches succeeded. To translate into a language without targeting a country, use POST /datasets/{dataset_id}/translate. Set estimate=true to price the request without starting a run.

ParametersExpand Collapse

dataset_id: str

sample_rate: float

Fraction of this dataset’s rows to expand, per target. At 0.25 with two targets, a 1,000-row dataset gains 500 rows and the new dataset holds 1,500.

minimum0.01

maximum1

estimate: Optional[bool]

When true, validates the request and returns the estimated credit cost without starting a run or creating a dataset.

idempotency_key: Optional[str]

Opaque key that makes a retried request safe. A second request carrying the same key returns the dataset the first one created instead of starting and charging for a second run.

maxLength255

pairs: Iterable[Pair]

Target country/language pairs. Each sampled row gains one row localized to each pair — translated into the language and adapted to that country’s conventions. Unsupported combinations are rejected.

country: str

ISO 3166-1 alpha-2 country code.

language: str

Language code, as ISO 639-1 — optionally with a script subtag. Supported pairs include codes that are not two letters (zh-Hant for Taiwan, yue for Hong Kong), so the length is not pinned at two here. Membership is decided against the supported-pair list, which names an unsupported entry in its own 400.

ReturnsExpand Collapse

class DatasetLocalizeResponse: …

dataset_id: Optional[str]

The expanded dataset. It carries this dataset’s rows plus the new ones, and is ready to download once its status reaches succeeded. Null for an estimate, which creates nothing.

status: Optional[Literal["pending", "running", "awaiting_input", 2 more]]

Status of the expanded dataset at the moment this response was sent, in the same vocabulary GET /datasets/{dataset_id}/status reports. Poll that endpoint until it reaches succeeded or failed. An idempotent replay of a finished run returns its terminal status here.

One of the following:

"pending"

"running"

"awaiting_input"

"succeeded"

"failed"

estimated_credits_consumed: float

Credits this run consumes, charged against the rows it adds. Zero on an idempotent replay: the earlier run reserved the credits, and this call charges nothing.

estimate: bool

Whether this was an estimate-only request (no run started).

estimated_new_rows: float

Rows this run adds, which is what the credit cost is charged against. Zero on an idempotent replay, which adds none.

Add localized rows to a dataset

import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
response = client.datasets.localize(
    dataset_id="dataset_id",
    sample_rate=0.25,
    pairs=[{
        "country": "ES",
        "language": "ca",
    }],
)
print(response.dataset_id)

{
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "estimated_credits_consumed": 5,
  "estimate": true,
  "estimated_new_rows": 500
}

Returns Examples

{
  "dataset_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "estimated_credits_consumed": 5,
  "estimate": true,
  "estimated_new_rows": 500
}