Localisation and URLs

7 views Markdown

The five endpoints behind the installation's language, currency, time zone and address structure.

Overview

These five endpoints decide which language, which currency and which addresses the installation runs on. They look like small settings, but three of them reach across the whole installation, and this article is largely about those.

The time zone and the date format change safely. The locale, the currency, the country and the address mode write files, flip tables or create folders; change those on a live installation with care.

Reference

Reading the Localisation

get/api/v1/admin/settings/localisation
Settings/GetLocalisationSettings admin options included

Returns the installation's language, currency, country and time zone.

Response fields data — 8
languagestringThe default language.
localstringThe default locale. It decides the number and date formats.
currencyintId of the default currency.
countrystringThe default country.
timezonestringThe time zone.
date_formatstringHow dates are displayed.
ip_modulestringThe module that resolves a visitor's location.
availableobjectThe time zones you can pick and the location modules installed. Present on the read only.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/settings/localisation' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/settings/localisation', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/localisation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The values you can pick come back in the SAME response; no separate reference call is needed.
$loc   = Api::Settings()->GetLocalisationSettings()['data'];
$zones = $loc['available']['timezones'];

Writing the Localisation

put/api/v1/admin/settings/localisation
Settings/UpdateLocalisationSettings admin high risk

Applies the settings you send. Three of the fields have side effects across the installation.

Body 8
languagestringThe default language.
localstringThe default locale. Changing it rewrites the language package file.
currencyintId of the default currency. Changing it flips the currency table and starts an exchange rate sync.
countrystringThe default country. Moving away from one particular country switches off the identity number fields.
timezonestringThe time zone.
date_formatstringHow dates are displayed.
ip_modulestringThe location module. It has to be installed.
ip_module_configobjectThe location module's settings. Sent together with the module only.
Response fields data — 8
dataobjectThe settings as they now stand. Same shape as the read endpoint.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/localisation' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"timezone":"America/New_York","date_format":"Y-m-d"}'
const res = await fetch('https://panel.example.com/api/v1/admin/settings/localisation', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    timezone: 'America/New_York',
    date_format: 'Y-m-d',
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/localisation');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'timezone'    => 'America/New_York',
        'date_format' => 'Y-m-d',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The time zone and the date format are the SAFE fields; the locale, currency and country are not.
Api::Settings()->UpdateLocalisationSettings([
    'timezone'    => 'America/New_York',
    'date_format' => 'Y-m-d',
]);

Reading the Address Settings

get/api/v1/admin/settings/url
Settings/GetUrlSettings admin

Returns how addresses are formed and the path names in each language.

Response fields data — 2
rich_urlstringThe address mode. One of three: clean addresses, plain addresses, and a middle mode.
routesobjectThe path names, keyed by language. In each, a map from route key to path segment.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/settings/url' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/settings/url', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/url');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The path names are per language: the same page opens on a different address in each.
$url = Api::Settings()->GetUrlSettings()['data'];
$en  = $url['routes']['en']['products'];

Changing the Address Mode

put/api/v1/admin/settings/url
Settings/UpdateUrlSettings admin affects panel access

Switches addresses between clean and plain, testing the server's support live.

Body 1
rich_urlstringrequiredThe new address mode. Sending the value it already has does nothing, and is safe.
Response fields data — 2
dataobjectThe settings as they now stand. Same shape as the read endpoint. A reply means the live check passed and the new mode is in force; on failure the old one stays.
Errors 2
mod_rewrite_failed422The server does not support clean addresses. The check runs live, and on failure the mode is left alone.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/url' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"rich_url":"on"}'
const res = await fetch('https://panel.example.com/api/v1/admin/settings/url', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rich_url: 'on' }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/url');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['rich_url' => 'on']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// This endpoint creates or removes the ADMIN FOLDER: a wrong mode can break the panel address.
// Read the current mode first; sending the same value is harmless.
$current = Api::Settings()->GetUrlSettings()['data']['rich_url'];

if ($current !== 'on') {
    Api::Settings()->UpdateUrlSettings(['rich_url' => 'on']);
}

Writing the Path Names

put/api/v1/admin/settings/url/views
Settings/UpdateUrlViews admin old addresses break

Writes the path names that appear in page addresses, per language.

Body 1
routesobjectrequiredThe path names, keyed by language. Only route keys that already exist are written; an unknown key is ignored.
Response fields data — 2
dataobjectThe address settings as they now stand. Same shape as the read endpoint.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/settings/url/views' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"routes":{"en":{"products":"products","cart":"cart"}}}'
const res = await fetch('https://panel.example.com/api/v1/admin/settings/url/views', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    routes: { en: { products: 'products', cart: 'cart' } },
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/settings/url/views');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'routes' => ['en' => ['products' => 'products']],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Changing a path name breaks the OLD address, the one in search engines and in links people saved.
// Read the keys from the current structure; an invented key is skipped without a word.
$routes = Api::Settings()->GetUrlSettings()['data']['routes'];
$routes['en']['products'] = 'shop';

Api::Settings()->UpdateUrlViews(['routes' => $routes]);

Pitfalls

The address mode rebuilds the panel folder

Changing the mode tests live whether the server supports clean addresses, and creates or removes the admin folder. A wrong mode can leave the panel unreachable. Sending the value it already has does nothing, so reading the current mode first is the safest route.

A currency change flips the table

Changing the default currency does not merely update a preference: the local flag moves in the currency table and an exchange rate sync starts. How prices look changes across the installation. Do not do it during trading hours.

The locale rewrites the language file

Changing the default locale causes the language package file to be rewritten. That is a different kind of act from saving a setting: a file on disk changes. The locale is best set once at installation and left alone.

The country can switch off the identity fields

Moving the default country away from one particular country switches off the identity number fields on the registration form. It is a silent side effect: the form changes though you touched nothing in the client registration settings.

Changing a path name breaks the old address

Change a page's path name and the old address stops working: search engine entries and links clients saved go nowhere, and no redirect is set up. An unrecognised route key is also ignored without a word, so a path you thought you wrote may never have been written. Confirm the result through the read endpoint.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket

We use cookies to keep you signed in, remember your language and currency, and improve the site. Cookie Policy