second first commit

2026-09-22 08:57:00 -04:00
parent e88d7e2ff3
commit 0aef7fb2d8
4766 changed files with 1236986 additions and 0 deletions
@@ -0,0 +1,108 @@
+# Translate
+
+**Protocol:** JSON 1.1 (`X-Amz-Target: AWSShineFrontendService_20170701.*`)
+**Endpoint:** `POST http://localhost:4566/`
+
+## Supported Actions
+
+<!-- floci:actions:start -->
+| Action | Description |
+| --- | --- |
+| `TranslateText` | Translate a UTF-8 text string between two languages |
+| `TranslateDocument` | Translate a document (≤100 KB) supplied as a base64 blob |
+| `ListLanguages` | List the language codes and names Floci recognizes |
+<!-- floci:actions:end -->
+
+## Emulation Behavior
+
+- **No machine translation:** `TranslateText` returns the request `Text` verbatim as
+  `TranslatedText`, and `TranslateDocument` returns the request `Document.Content` bytes
+  unchanged as `TranslatedDocument.Content`. To exercise logic that branches on a specific
+  translation, use the mock config below.
+- **Language detection:** a `SourceLanguageCode` of `auto` is accepted and reported back
+  as `en` (the stub's fixed "detected" language); no Comprehend call is made.
+- **Real input validation:** `Text` / `Document.Content` / `Document.ContentType` and both
+  language codes are required. `SourceLanguageCode` must be `auto` or a code from the
+  catalog returned by `ListLanguages`; `TargetLanguageCode` must be a catalog code. An
+  unknown code returns `UnsupportedLanguagePairException`.
+  - `TranslateText` rejects a `Text` longer than 10,000 UTF-8 bytes with
+    `TextSizeLimitExceededException`, matching AWS. Any language pair is allowed
+    (`TranslateText` is any-to-any).
+  - `TranslateDocument` requires an **English pivot**: either the source or the target
+    language must resolve to `en`, otherwise it returns `UnsupportedLanguagePairException`.
+    It also rejects a `ContentType` other than `text/plain`, `text/html`, or the
+    Word (`.docx`) MIME type, a `Content` that is not valid base64, and a decoded
+    document over 100 KB, all with `InvalidRequestException` (`TranslateDocument` does
+    not model `TextSizeLimitExceededException`).
+- **Fixed catalog:** `ListLanguages` returns a curated ~35-language subset of Translate's
+  full list, enough to drive an i18n pipeline. `MaxResults` / `NextToken` are accepted
+  but ignored (the whole catalog fits in one page, so no `NextToken` is returned).
+  `DisplayLanguageCode` is validated against the AWS enum
+  (`de`, `en`, `es`, `fr`, `it`, `ja`, `ko`, `pt`, `zh`, `zh-TW`) but every `LanguageName`
+  is returned in English regardless.
+- **Out of scope:** custom terminology, parallel data, asynchronous batch translation jobs
+  (`StartTextTranslationJob` and friends), and tagging, all needing persistent state.
+- **Deviation:** `ListLanguages` always returns `LanguageName`s in English regardless of
+  `DisplayLanguageCode` (real Translate localizes them), and the `Formality` /
+  `Profanity` / `Brevity` translation settings are accepted but ignored.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_TRANSLATE_ENABLED` | `true` | Enable or disable the service |
+| `AI_MOCK_CONFIG` | unset | Path to a shared mock-response config file; see "Mock Responses" below |
+
+## Mock Responses
+
+To return a real translated string instead of the echoed input, point `AI_MOCK_CONFIG` at a
+JSON file shared across Translate, Comprehend, Textract, and Rekognition:
+
+```json
+{
+  "translate": {
+    "Hello world": {
+      "TranslateText": { "TranslatedText": "Hola mundo", "SourceLanguageCode": "en", "TargetLanguageCode": "es" }
+    }
+  }
+}
+```
+
+The lookup key is the **exact `Text` value** sent in the request, so only `TranslateText`
+can be mocked; `TranslateDocument` carries a binary payload with no stable key. The file is
+re-read when its modification time changes, so it can be edited without restarting the
+emulator. A missing file, an unset `AI_MOCK_CONFIG`, or no matching entry all fall back to
+the echoed-input default. Mocking is opt-in and never breaks a call that isn't using it.
+
+## Examples
+
+```bash
+export AWS_ENDPOINT_URL=http://localhost:4566
+
+aws translate translate-text \
+  --text "Floci makes local AWS testing painless" \
+  --source-language-code en \
+  --target-language-code fr \
+  --endpoint-url $AWS_ENDPOINT_URL
+
+aws translate list-languages \
+  --endpoint-url $AWS_ENDPOINT_URL
+```
+
+## SDK Example (Java)
+
+```java
+TranslateClient translate = TranslateClient.builder()
+    .endpointOverride(URI.create("http://localhost:4566"))
+    .region(Region.US_EAST_1)
+    .credentialsProvider(StaticCredentialsProvider.create(
+        AwsBasicCredentials.create("test", "test")))
+    .build();
+
+TranslateTextResponse response = translate.translateText(req -> req
+    .text("Floci makes local AWS testing painless")
+    .sourceLanguageCode("en")
+    .targetLanguageCode("fr"));
+
+System.out.println("Translated: " + response.translatedText());
+```