add regional endpoint documentation

docs.json

@@ -40,6 +40,7 @@
               "docs/getting-started/intro",
               "docs/getting-started/about",
               "docs/getting-started/auth",
+              "docs/getting-started/regional-endpoints",
               "docs/getting-started/client-libraries",
               "docs/getting-started/managing-api-keys",
               "docs/getting-started/your-first-api-request",

docs/getting-started/regional-endpoints.mdx

@@ -0,0 +1,201 @@
+---
+title: "Regional API Endpoints"
+description: "Reference documentation for DeepL's regional API endpoints, including endpoint URLs, configuration, and technical specifications."
+public: false
+---
+
+DeepL offers regional API endpoints that process and store data within specific geographic regions. Regional endpoints provide the same API functionality as the standard endpoint, with data processing occurring in data centers located in specific regions. These endpoints help organizations meet data residency and compliance requirements, and can also reduce latency for users in specific geographic regions.
+
+<Warning>
+Regional endpoints are only available to customers who have signed a regional deployment addendum. Without a signed addendum, requests to regional endpoints will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to discuss access.
+</Warning>
+
+## Endpoint URLs
+
+DeepL currently offers the following regional endpoints:
+
+| **Region** | **Endpoint URL** |
+|------------|------------------|
+| **United States** | `https://api-us.deepl.com` |
+| **Japan** | `https://api-jp.deepl.com` |
+| **European Union (default)** | `https://api.deepl.com` |
+
+
+---
+
+## Configuration
+
+Regional endpoints are configured by specifying the endpoint URL in the API client. The standard endpoint URL (`https://api.deepl.com`) is replaced with the regional endpoint URL (`https://api-us.deepl.com` or `https://api-jp.deepl.com`).
+
+<Tabs>
+<Tab title="cURL">
+
+```bash
+# Standard endpoint
+curl -X POST 'https://api.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+  "text": ["Hello, world!"],
+  "target_lang": "DE"
+}'
+
+# US regional endpoint
+curl -X POST 'https://api-us.deepl.com/v2/translate' \
+--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
+--header 'Content-Type: application/json' \
+--data '{
+  "text": ["Hello, world!"],
+  "target_lang": "DE"
+}'
+```
+
+</Tab>
+<Tab title="Python">
+
+The Python client library accepts a `server_url` parameter:
+
+```python
+import deepl
+
+# Standard endpoint
+translator = deepl.Translator("[yourAuthKey]")
+
+# US regional endpoint
+translator = deepl.Translator(
+    "[yourAuthKey]",
+    server_url="https://api-us.deepl.com"
+)
+
+# Usage remains identical
+result = translator.translate_text("Hello, world!", target_lang="DE")
+print(result.text)
+```
+
+</Tab>
+<Tab title="Node.js">
+
+The Node.js client library accepts a `serverUrl` option:
+
+```javascript
+const deepl = require('deepl-node');
+
+// Standard endpoint
+const translator = new deepl.Translator('[yourAuthKey]');
+
+// US regional endpoint
+const translator = new deepl.Translator(
+    '[yourAuthKey]',
+    { serverUrl: 'https://api-us.deepl.com' }
+);
+
+// Usage remains identical
+(async () => {
+    const result = await translator.translateText('Hello, world!', null, 'de');
+    console.log(result.text);
+})();
+```
+
+</Tab>
+<Tab title="Java">
+
+The Java client library accepts a `TranslatorOptions` object with `setServerUrl()` method:
+
+```java
+import com.deepl.api.*;
+
+// Standard endpoint
+Translator translator = new Translator("[yourAuthKey]");
+
+// US regional endpoint
+TranslatorOptions options = new TranslatorOptions()
+    .setServerUrl("https://api-us.deepl.com");
+Translator translator = new Translator("[yourAuthKey]", options);
+
+// Usage remains identical
+TextResult result = translator.translateText("Hello, world!", null, "de");
+System.out.println(result.getText());
+```
+
+</Tab>
+<Tab title="C# / .NET">
+
+The .NET client library accepts a `TranslatorOptions` object with `ServerUrl` property:
+
+```csharp
+using DeepL;
+
+// Standard endpoint
+var translator = new Translator("[yourAuthKey]");
+
+// US regional endpoint
+var translator = new Translator(
+    "[yourAuthKey]",
+    new TranslatorOptions { ServerUrl = "https://api-us.deepl.com" }
+);
+
+// Usage remains identical
+var result = await translator.TranslateTextAsync("Hello, world!", null, "de");
+Console.WriteLine(result.Text);
+```
+
+</Tab>
+<Tab title="PHP">
+
+The PHP client library accepts a `server_url` option in the options array:
+
+```php
+use DeepL\Translator;
+
+// Standard endpoint
+$translator = new Translator('[yourAuthKey]');
+
+// US regional endpoint
+$translator = new Translator(
+    '[yourAuthKey]',
+    ['server_url' => 'https://api-us.deepl.com']
+);
+
+// Usage remains identical
+$result = $translator->translateText('Hello, world!', null, 'de');
+echo $result->text;
+```
+
+</Tab>
+</Tabs>
+
+---
+
+## Technical specifications
+
+### Access requirements
+
+Regional endpoints require activation through a regional deployment addendum. Requests to regional endpoints without activation will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to activate regional endpoints for your account.
+
+If your account has regional endpoint access, any API key can be used with any regional endpoint.
+
+### API compatibility
+
+Regional endpoints support all DeepL API functionality except:
+
+- Voice API
+- Admin Analytics API
+
+These endpoints are only available on the standard `api.deepl.com` endpoint. 
+
+### Glossaries and style rules
+
+Glossaries and style rules are unique to each of DeepL's regional data centers and are not shared between them. Glossaries and style rules created via the API on one regional endpoint (e.g., `api-us.deepl.com`) are only accessible from that same endpoint.
+
+Additionally, the DeepL web UI (at [deepl.com](https://www.deepl.com)) currently only accesses the European Union data center. Glossaries and style rules created in the UI are only accessible via the standard `api.deepl.com` endpoint, not regional endpoints like `api-us.deepl.com` or `api-jp.deepl.com`.
+
+For more details, see the [Style rules documentation](/api-reference/style-rules).
+
+---
+
+## Related documentation
+
+- [Client libraries](/docs/getting-started/client-libraries) - Language-specific client library documentation and configuration
+- [Authentication and access](/docs/getting-started/auth) - API authentication methods and security best practices
+- [Text translation](/api-reference/translate) - Text translation API reference
+- [Admin API](/api-reference/admin-api) - Programmatic API key management for enterprise administrators