Merge remote-tracking branch 'origin/main' into glossary-languages

Author: morsssss

.mintignore

@@ -0,0 +1 @@
+reviews/*

README.md

@@ -81,6 +81,10 @@ For the highest quality documentation, use both the diataxis plugin and docs-rev
 
 This two-pass approach ensures both structural correctness (via diataxis) and editorial quality (via docs-reviewer).
 
+3. **Check for broken links:**
+
+Finally, you can run `mint broken-links` and `mint broken-links --check-anchors` to ensure all links are correct.
+
 ### Future Plans
 
 - Add a subagent to search our codebase and backstage

_assets/images/php-proxy-screenshot.png

@@ -9,7 +9,7 @@ The text-translation API currently consists of a single endpoint, `translate`, w
 
 For highest translation quality, we recommend using our next-gen models. For details, please see [here](/docs/api-reference/translate#about-the-model-type-parameter).
 
-To learn more about context in DeepL API translations, see our [context parameter guide](/docs/learning-how-tos/how-to-use-context-parameter).
+To learn more about context in DeepL API translations, see our [context parameter guide](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter).
 
 For more detail about request body parameters, see the [Request Body Descriptions](/api-reference/translate#request-body-descriptions) section further down on the page.
 

api-reference/translate.mdx

@@ -399,11 +399,11 @@
     },
     {
       "source": "/docs/best-practices/working-with-context",
-      "destination": "/docs/learning-how-tos/how-to-use-context-parameter"
+      "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter"
     },
     {
       "source": "/docs/learning-how-tos/cookbook/context-parameter-examples",
-      "destination": "/docs/learning-how-tos/how-to-use-context-parameter"
+      "destination": "/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter"
     }
   ],
   "integrations": {

docs.json

@@ -94,6 +94,6 @@ Combining `custom_instructions` with `model_type: latency_optimized` will result
 ## Related documentation
 
 - [Text translation API reference](/api-reference/translate)
-- [Working with context](/docs/examples-and-guides/how-to-use-context-parameter)
+- [Working with context](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter)
 - [Style rules API](/api-reference/style-rules)
 - [Multilingual glossaries](/api-reference/multilingual-glossaries)

docs/best-practices/custom-instructions.mdx

@@ -11,5 +11,5 @@ As you prepare to open your DeepL-powered application up to the world, these tip
    * Uploading a file for document translation requires an HTTP POST request with `Content-Type: multipart/form-data`; this content type should not be used for text translation.
 4. **No query parameters:** Please do not make API requests using query parameters. The examples throughout the API reference include properly formed HTTP POST requests. For security reasons, be especially sure not to send your authentication key via query parameters.
 5. **CORS requests:** It's not possible to send requests to the DeepL API from the browser, as requests to third-party APIs from front-end applications would expose your credentials on the web. [You can learn more here](/docs/best-practices/cors-requests).
-6. **Translation context:** DeepL considers the broader context of a source text or document when translating. In general, including more context in a source text or document can result in a higher-quality DeepL translation. For text translation, you can also try the [`context` parameter](/api-reference/translate#request-body-descriptions). [Learn more about working with context here](/docs/best-practices/working-with-context).
+6. **Translation context:** DeepL considers the broader context of a source text or document when translating. In general, including more context in a source text or document can result in a higher-quality DeepL translation. For text translation, you can also try the [`context` parameter](/api-reference/translate#request-body-descriptions). [Learn more about working with context here](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter).
 7. **Cache results from translation requests:** Storing API responses lets apps serve content faster and avoids extra costs from repeated requests for unchanged content.

docs/best-practices/pre-production-checklist.mdx

@@ -1,36 +1,94 @@
 ---
-title: "Node.js Proxy Server"
-description: "A lightweight local proxy for the DeepL API that enables browser-based applications to bypass CORS restrictions."
+title: "Making API calls from client-side JavaScript"
+description: "Two lightweight local proxies that let you try the DeepL API directly from a website"
 public: true
 ---
 
+<Note>
+These proxies are intended for prototyping and frontend testing. For production environments, consider implementing your own backend service with additional security measures and rate limiting.
+</Note>
+
+## Rationale
+
+The DeepL API does not permit calls from client-side JavaScript - that is, from JavaScript running in a browser. This policy exists to keep your API key safe. When you place a call from your website directly to the DeepL API, that call needs to include your API key. Anyone using your website could look at the network calls or your code itself, find your API key, and use it themselves.
+
+For this and other security considerations, DeepL [does not enable the CORS headers](/docs/best-practices/cors-requests) you would need to call the API from a webpage hosted on your origin. The industry-standard approach is to call APIs like DeepL’s from a back-end service. DeepL enforces this best practice to keep your credentials secure.
+
+## When to use a quick proxy
+
+But what do you do if you want to use the API quickly, in a prototype, a demo, or a hackathon, where you need to get up and running fast? What if you don’t have easy access to a server?
+
+For such situations, here are two solutions.
+
+## Node.js Proxy Server
+
 <Card title="GitHub - DeepLcom/deepl-api-nodejs-proxy" icon="github" horizontal href="https://github.com/DeepLcom/deepl-api-nodejs-proxy">
   DeepL API Node.js Proxy on GitHub
 </Card>
 
+This full-featured proxy server supports all DeepL API endpoints, including text translation, document translation, and glossaries. Built with Node.js and Express with minimal dependencies, it handles CORS headers for you and keeps your API key secure. It even includes an interactive web demo for testing translations right in your browser.
 
-## Overview
+This proxy includes an interactive setup wizard to get you started quickly. Clone the repo, run the setup, and start sending requests from your browser. Check out the [GitHub repository](https://github.com/DeepLcom/deepl-api-nodejs-proxy) for full setup instructions and Docker support.
 
-This lightweight proxy server lets you call the DeepL API directly from browser-based applications. In simpler terms, it lets you make DeepL API calls from your client-side JavaScript without running into browser security restrictions.
+## Quick & dirty PHP proxy
 
-Since the DeepL API doesn't allow direct browser requests (see [CORS requests documentation](/docs/best-practices/cors-requests)), this proxy handles CORS headers and keeps your API key secure. Perfect for hackathons, demos, and quick prototypes where you need to get up and running fast.
+If you’re just using our `/translate` endpoint and want an even quicker solution, or if you don’t use node.js, you could use the PHP code below to create an instant proxy server. If PHP is not already installed on your machine, you can download and install it at [php.net](https://www.php.net/downloads.php).
 
-Built with Node.js and Express with minimal dependencies. Supports all DeepL API endpoints including text translation, document translation, and glossaries. Includes an interactive web demo for testing translations right in your browser.
+The PHP script takes the parameters in the query string and passes them into a `POST` request to `/translate`. It does not check that the parameters are valid and does not support any other endpoints, although you could modify it to do so.
 
-<Note>
-This proxy is intended for prototyping and frontend testing. For production environments, consider implementing your own backend service with additional security measures and rate limiting.
-</Note>
+To use this while developing on your local machine:
+
+* replace `{your API key here}` with your actual API key   
+* create a file in your favorite directory with the PHP code below  
+* go to your terminal and visit that directory  
+* type `php -S localhost:8000`
+
+Your JavaScript can then access the DeepL API at `http://localhost:8000/php-proxy.php`. For example, to send a translation request with `text` and `target_lang`:
+
+```javascript
+const url = `http://localhost:8000/deepl-proxy.php?text=${encodeURIComponent(text)}&target_lang=${encodeURIComponent(targetLang)}`;
+const response = await fetch(url);
+const result = await response.text();
+```
+
+Here is the PHP script:
 
-## Quick Start
+```php
+<?php
+header('Content-Type: application/json');
+header('Access-Control-Allow-Origin: *');
+
+$apiKey = '{your API key here}';
+$apiUrl = 'https://api.deepl.com/v2/translate';
+
+$data = http_build_query($_GET);
+
+$context = stream_context_create([
+  'http' => [
+      'method' => 'POST',
+      'header' => "Authorization: DeepL-Auth-Key " . $apiKey . "\r\n" .
+                  "Content-Type: application/x-www-form-urlencoded\r\n",
+      'content' => $data
+  ]
+]);
+
+echo file_get_contents($apiUrl, false, $context);
+?>
+```
 
-The proxy includes an interactive setup wizard to get you started quickly. Clone the repo, run the setup, and start sending requests from your browser. Check out the [GitHub repository](https://github.com/DeepLcom/deepl-api-nodejs-proxy) for full setup instructions and Docker support.
 
 ## Screenshots
 
-<Frame>
+### Node.js proxy
+<Frame caption="Node.js proxy server running in a terminal">
   <img src="https://raw.githubusercontent.com/DeepLcom/deepl-api-nodejs-proxy/main/assets/proxy-running.png" alt="Node.js proxy server running and ready to accept requests" />
 </Frame>
 
-<Frame>
+<Frame caption="Interactive web demo interface for testing translations">
   <img src="https://raw.githubusercontent.com/DeepLcom/deepl-api-nodejs-proxy/main/assets/dashboard-demo.png" alt="Interactive web demo interface for testing translations" />
 </Frame>
+
+### PHP proxy
+<Frame caption='PHP proxy running in a terminal'>
+    ![](/_assets/images/php-proxy-screenshot.png)
+</Frame>

docs/learning-how-tos/cookbook/nodejs-proxy.mdx

@@ -130,5 +130,5 @@ Now that you understand how to translate between language variants:
 - **Try it yourself:** Test out style rules and custom instructions in the [text translation API playground](/api-reference/translate)
 - **Learn about the Write API:** Explore the [/write/rephrase endpoint](/api-reference/improve-text) for high-quality variant translation and rephrasing
 - **Manage reusable rules:** Learn how to create [style rules](/api-reference/style-rules) for systematic variant transformations
-- **Improve translation quality:** Understand how [the context parameter](/docs/best-practices/working-with-context) can enhance ambiguous translations
+- **Improve translation quality:** Understand how [the context parameter](/docs/learning-how-tos/examples-and-guides/how-to-use-context-parameter) can enhance ambiguous translations