Documentation menu

API Reference

Localization

Message catalog pull + player language preference

GET /api/plugin/localization/catalog

Pull the message catalog

Every supported locale plus, per locale, the effective key→value map (operator overrides merged over plugin defaults) and the current version. Cache it; re-pull on a LOCALIZATION_UPDATED event. Pass ?namespace=a,b to scope the messages to those namespaces (the SDK does this automatically, pulling only the plugin's own keys plus core 'hive').

Parameters

  • namespace string query

    Comma-separated namespaces to scope to; omit for the whole catalog.

Responses

  • 200 The catalog with its version (scoped if a namespace was given).
200 response 
{
  "version": 0,
  "defaultLocale": "string",
  "locales": [
    {
      "locale": "string",
      "displayName": "string",
      "isDefault": false,
      "enabled": false
    }
  ],
  "messages": {}
}

Request

~
curl -X GET https://api.hivescale.dev/api/plugin/localization/catalog?namespace=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/localization/catalog?namespace=value"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
POST /api/plugin/localization/defaults

Declare default strings

Insert-missing-only: registers a namespace's compiled-in default strings for one locale so operators can discover and translate them. Never overwrites an operator edit or a prior default, so call it on every boot. Returns the number of newly added keys.

Request body

application/json 
{
  "namespace": "string",
  "locale": "string",
  "entries": {}
}

Responses

  • 200 { inserted } — count of newly registered keys.
  • 400 Bad Request
200 response 
{}

Request

~
curl -X POST https://api.hivescale.dev/api/plugin/localization/defaults \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"string","locale":"string","entries":{}}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"namespace\":\"string\",\"locale\":\"string\",\"entries\":{}}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/localization/defaults"))
    .header("X-Hive-Api-Key", apiKey)
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
GET /api/plugin/localization/locales

List supported locales

The languages this network offers, default first — the options for an in-game picker.

Responses

  • 200 Supported locales.
200 response 
[
  {
    "locale": "string",
    "displayName": "string",
    "isDefault": false,
    "enabled": false
  }
]

Request

~
curl -X GET https://api.hivescale.dev/api/plugin/localization/locales \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/localization/locales"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
GET /api/plugin/localization/players/{uuid}/locale

Read a player's language

The player's chosen language and its source (PLAYER = explicit, AUTO = detected). Both null when the player has never had a language set (auto-resolve on join).

Parameters

  • uuid string path required

    Player UUID.

Responses

  • 200 The player's language preference (locale/source may be null).
200 response 
{
  "locale": "string",
  "source": "string"
}

Request

~
curl -X GET https://api.hivescale.dev/api/plugin/localization/players/{uuid}/locale \
  -H "X-Hive-Api-Key: $HIVE_API_KEY"
HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/localization/players/{uuid}/locale"))
    .header("X-Hive-Api-Key", apiKey)
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());
PUT /api/plugin/localization/players/{uuid}/locale

Set a player's language

Persists the player's language. Use source=PLAYER for an in-game picker choice (sticky; never re-prompted) or source=AUTO for a detected seed (may be re-detected). A null locale clears it back to auto-resolve.

Parameters

  • uuid string path required

    Player UUID.

  • username string query

    Current username, to seed the row if unseen.

Request body

application/json 
{
  "locale": "string",
  "source": "string"
}

Responses

  • 200 The stored preference.
  • 400 Bad Request
200 response 
{
  "locale": "string",
  "source": "string"
}

Request

~
curl -X PUT https://api.hivescale.dev/api/plugin/localization/players/{uuid}/locale?username=value \
  -H "X-Hive-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locale":"string","source":"string"}'
HttpClient client = HttpClient.newHttpClient();

String body = "{\"locale\":\"string\",\"source\":\"string\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.hivescale.dev/api/plugin/localization/players/{uuid}/locale?username=value"))
    .header("X-Hive-Api-Key", apiKey)
    .header("Content-Type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response =
    client.send(request, HttpResponse.BodyHandlers.ofString());