From c27e719d22bbf0c57ef07453e400f3d7aa06aa08 Mon Sep 17 00:00:00 2001
From: Brent Shaffer <betterbrent@google.com>
Date: Thu, 4 Jun 2026 16:55:35 -0700
Subject: [PATCH 1/2] docs(Translate): remove section about removed client
 class

---
 Translate/README.md | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/Translate/README.md b/Translate/README.md
index 7df8e7d483a5..f51d4c5ced7b 100644
--- a/Translate/README.md
+++ b/Translate/README.md
@@ -55,17 +55,6 @@ try {
 }
 ```
 
-### Choosing the Right Client for You
-
-This component offers both a handwritten and generated client, used to access the V2 and V3 translation APIs, respectively.
-Both clients will receive on-going support and feature additions, however, it is worth noting the streamlined nature of
-the generated client means it will receive updates more frequently. Additionally, the generated client is capable of
-utilizing gRPC for its transport (by installing the gRPC extension) while the handwritten client interacts over
-REST & HTTP/1.1 only.
-
-The handwritten client can be found under `Google\Cloud\Translate\TranslateClient`, whereas the generated client is
-found under `Google\Cloud\Translate\V3\TranslationServiceClient`.
-
 ### Debugging
 
 Please see our [Debugging guide](https://github.com/googleapis/google-cloud-php/blob/main/DEBUG.md)

From 95d4fe7c91b0f7ab6f311746040f3effd62d3e17 Mon Sep 17 00:00:00 2001
From: Brent Shaffer <betterbrent@google.com>
Date: Thu, 4 Jun 2026 18:29:09 -0700
Subject: [PATCH 2/2] docs(Translate): add MIGRATING.md

---
 Translate/MIGRATING.md | 127 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 Translate/MIGRATING.md

diff --git a/Translate/MIGRATING.md b/Translate/MIGRATING.md
new file mode 100644
index 000000000000..aec42db23261
--- /dev/null
+++ b/Translate/MIGRATING.md
@@ -0,0 +1,127 @@
+# Migration Guide
+
+This migration guide shows how to migrate `google/cloud-translate` to v2.
+
+**NOTE**: The package version (e.g. `google/cloud-translate:^2.0`) is distinct
+from the Translate API version `V3`, which this package calls.
+
+## Client Initialization
+
+The `TranslateClient` has been replaced by `TranslationServiceClient`.
+
+**Before**
+```php
+use Google\Cloud\Translate\TranslateClient;
+
+$translate = new TranslateClient();
+```
+
+**After**
+```php
+use Google\Cloud\Translate\V3\Client\TranslationServiceClient;
+
+$translate = new TranslationServiceClient();
+```
+
+## Translate Text
+
+The `translate()` method has been replaced by `translateText()`. The arguments have also changed to accept a request object.
+
+### Single Translation
+
+**Before**
+```php
+use Google\Cloud\Translate\TranslateClient;
+
+$translate = new TranslateClient([
+    'projectId' => 'my-project'
+]);
+
+$result = $translate->translate('Hello, world!', [
+    'target' => 'fr'
+]);
+
+echo $result['text'];
+```
+
+**After**
+```php
+use Google\Cloud\Translate\V3\Client\TranslationServiceClient;
+use Google\Cloud\Translate\V3\TranslateTextRequest;
+
+$translate = new TranslationServiceClient();
+
+$projectId = 'my-project';
+$location = 'global';
+$parent = $translate->locationName($projectId, $location);
+
+$request = (new TranslateTextRequest())
+    ->setContents(['Hello, world!'])
+    ->setTargetLanguageCode('fr')
+    ->setParent($parent);
+
+$response = $translate->translateText($request);
+
+echo $response->getTranslations()[0]->getTranslatedText();
+```
+
+### Batch Translation
+
+**Before**
+```php
+use Google\Cloud\Translate\TranslateClient;
+
+$translate = new TranslateClient([
+    'projectId' => 'my-project'
+]);
+
+$results = $translate->translateBatch([
+    'Hello, world!',
+    'My name is Jeff.'
+], [
+    'target' => 'fr'
+]);
+
+foreach ($results as $result) {
+    echo $result['text'] . "
+";
+}
+```
+
+**After**
+```php
+use Google\Cloud\Translate\V3\Client\TranslationServiceClient;
+use Google\Cloud\Translate\V3\TranslateTextRequest;
+
+$translate = new TranslationServiceClient();
+
+$projectId = 'my-project';
+$location = 'global';
+$parent = $translate->locationName($projectId, $location);
+
+$request = (new TranslateTextRequest())
+    ->setContents([
+        'Hello, world!',
+        'My name is Jeff.'
+    ])
+    ->setTargetLanguageCode('fr')
+    ->setParent($parent);
+
+$response = $translate->translateText($request);
+
+foreach ($response->getTranslations() as $translation) {
+    echo $translation->getTranslatedText() . "
+";
+}
+```
+
+## Formatting Project Name
+
+In `v2`, you need to provide a formatted project name as the parent. You can use
+the `locationName` method on the client to format this.
+
+```php
+$projectId = 'my-project';
+$location = 'global';
+$parent = $translate->locationName($projectId, $location);
+```