Skip to content

Commit afc4a2a

Browse files
mziccardmziccard
authored
Add README and package-info for Translate, update main README (#1186)
1 parent 8cc6db7 commit afc4a2a

5 files changed

Lines changed: 320 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ This client supports the following Google Cloud Platform services:
2222
- [Google Cloud Pub/Sub] (#google-cloud-pubsub-alpha) (Alpha - Not working on App Engine Standard)
2323
- [Google Cloud Resource Manager] (#google-cloud-resource-manager-alpha) (Alpha)
2424
- [Google Cloud Storage] (#google-cloud-storage)
25+
- [Google Cloud Translate] (#google-translate) (Alpha)
2526

2627
> Note: This client is a work-in-progress, and may occasionally
2728
> make backwards-incompatible changes.
@@ -569,6 +570,40 @@ if (blob != null) {
569570
}
570571
```
571572
573+
Google Translate
574+
----------------
575+
576+
- [API Documentation][translate-api]
577+
- [Official Documentation][translate-docs]
578+
579+
#### Preview
580+
581+
Here's a snippet showing a simple usage example. The example shows how to detect the language of
582+
some text and how to translate some text. The example assumes that the `GOOGLE_API_KEY` is set and
583+
contains a valid API key. Alternatively, you can use the `apiKey(String)` setter in
584+
`TranslateOptions.Builder` to set the API key. Complete source code can be found at
585+
[DetectLanguageAndTranslate.java](./gcloud-java-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java).
586+
587+
```java
588+
import com.google.cloud.translate.Detection;
589+
import com.google.cloud.translate.Translate;
590+
import com.google.cloud.translate.Translate.TranslateOption;
591+
import com.google.cloud.translate.TranslateOptions;
592+
import com.google.cloud.translate.Translation;
593+
594+
Translate translate = TranslateOptions.defaultInstance().service();
595+
596+
Detection detection = translate.detect("Hola");
597+
String detectedLanguage = detection.language();
598+
599+
Translation translation = translate.translate(
600+
"World",
601+
TranslateOption.sourceLanguage("en"),
602+
TranslateOption.targetLanguage(detectedLanguage));
603+
604+
System.out.printf("Hola %s%n", translation.translatedText());
605+
```
606+
572607
Troubleshooting
573608
---------------
574609
@@ -648,3 +683,6 @@ Apache 2.0 - See [LICENSE] for more information.
648683
[cloud-compute]: https://cloud.google.com/compute/
649684
[cloud-compute-docs]: https://cloud.google.com/compute/docs/overview
650685
[compute-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/compute/package-summary.html
686+
687+
[translate-docs]: https://cloud.google.com/translate/docs/
688+
[translate-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/translate/package-summary.html

‎gcloud-java-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/*
18+
* EDITING INSTRUCTIONS
19+
* This file is referenced in READMEs and javadoc. Any change to this file should be reflected in
20+
* the project's READMEs and package-info.java.
21+
*/
22+
23+
package com.google.cloud.examples.translate.snippets;
24+
25+
import com.google.cloud.translate.Detection;
26+
import com.google.cloud.translate.Translate;
27+
import com.google.cloud.translate.Translate.TranslateOption;
28+
import com.google.cloud.translate.TranslateOptions;
29+
import com.google.cloud.translate.Translation;
30+
31+
/**
32+
* A snippet for Google Translate showing how to detect the language of some text and translate
33+
* some other text.
34+
*/
35+
public class DetectLanguageAndTranslate {
36+
37+
public static void main(String... args) {
38+
// Create a service object
39+
// API key is read from the GOOGLE_API_KEY environment variable
40+
Translate translate = TranslateOptions.defaultInstance().service();
41+
42+
// Detect the language of some text
43+
Detection detection = translate.detect("Hola");
44+
String detectedLanguage = detection.language();
45+
46+
// Translate some text
47+
Translation translation = translate.translate(
48+
"World",
49+
TranslateOption.sourceLanguage("en"),
50+
TranslateOption.targetLanguage(detectedLanguage));
51+
52+
System.out.printf("Hola %s%n", translation.translatedText());
53+
}
54+
}

‎gcloud-java-translate/README.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
Google Cloud Java Client for Translate
2+
====================================
3+
4+
Java idiomatic client for [Google Translate](https://cloud.google.com/translate/).
5+
6+
[![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
7+
[![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
8+
[![Maven](https://img.shields.io/maven-central/v/com.google.cloud/gcloud-java-translate.svg)]( https://img.shields.io/maven-central/v/com.google.cloud/gcloud-java-translate.svg)
9+
[![Codacy Badge](https://api.codacy.com/project/badge/grade/9da006ad7c3a4fe1abd142e77c003917)](https://www.codacy.com/app/mziccard/gcloud-java)
10+
[![Dependency Status](https://www.versioneye.com/user/projects/56bd8ee72a29ed002d2b0969/badge.svg?style=flat)](https://www.versioneye.com/user/projects/56bd8ee72a29ed002d2b0969)
11+
12+
- [Homepage](https://googlecloudplatform.github.io/gcloud-java/)
13+
- [API Documentation](http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/translate/package-summary.html)
14+
15+
> Note: This client is a work-in-progress, and may occasionally
16+
> make backwards-incompatible changes.
17+
18+
Quickstart
19+
----------
20+
If you are using Maven, add this to your pom.xml file
21+
```xml
22+
<dependency>
23+
<groupId>com.google.cloud</groupId>
24+
<artifactId>gcloud-java-translate</artifactId>
25+
<version>0.2.7</version>
26+
</dependency>
27+
```
28+
If you are using Gradle, add this to your dependencies
29+
```Groovy
30+
compile 'com.google.cloud:gcloud-java-translate:0.2.7'
31+
```
32+
If you are using SBT, add this to your dependencies
33+
```Scala
34+
libraryDependencies += "com.google.cloud" % "gcloud-java-translate" % "0.2.7"
35+
```
36+
37+
Example Application
38+
-------------------
39+
40+
[`TranslateExample`](../gcloud-java-examples/src/main/java/com/google/cloud/examples/translate/TranslateExample.java) is a simple command line interface that provides some of Google Translate's functionality. Read more about using the application on the [`TranslateExample` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/cloud/examples/translate/TranslateExample.html).
41+
42+
Authentication
43+
--------------
44+
45+
Google Translate requires an API key to be passed with every request. For instructions on how to
46+
get an API key follow the [Translate quickstart](https://cloud.google.com/translate/v2/quickstart).
47+
48+
About Google Translate
49+
--------------------
50+
51+
[Google Translate][google-translate] provides a simple programmatic interface for translating an
52+
arbitrary string into any supported language. Translate is highly responsive, so websites and
53+
applications can integrate with Translate API for fast, dynamic translation of source text from the
54+
source language to a target language (e.g., French to English). Language detection is also
55+
available In cases where the source language is unknown.
56+
57+
See the [Translate quickstart](https://cloud.google.com/translate/v2/quickstart) for more details
58+
on how to activate Google Translate for your project.
59+
60+
See the ``gcloud-java`` API [Translate documentation][translate-api] to learn how to interact with
61+
the Google Translate using this Client Library.
62+
63+
Getting Started
64+
---------------
65+
#### Prerequisites
66+
For this tutorial, you need a [Google Developers Console](https://console.developers.google.com/)
67+
project with "Translate API" enabled via the console's API Manager. You will also need a to enable
68+
billing via the [Google Developers Console](https://console.developers.google.com/) project and to
69+
retrieve an API key. See [Translate quickstart](https://cloud.google.com/translate/v2/quickstart)
70+
for more details.
71+
72+
#### Installation and setup
73+
You'll need to obtain the `gcloud-java-translate` library. See the [Quickstart](#quickstart)
74+
section to add `gcloud-java-translate` as a dependency in your code.
75+
76+
#### Creating an authorized service object
77+
To make authenticated requests to Google Translates, you must create a service object with an API
78+
key. By default, API key is looked for in the `GOOGLE_API_KEY` environment variable. Once the API
79+
key is set, you can make API calls by invoking methods on the Translate service object. To create a
80+
service object, given that `GOOGLE_API_KEY` is set, use the following code:
81+
82+
```java
83+
import com.google.cloud.translate.Translate;
84+
import com.google.cloud.translate.TranslateOptions;
85+
86+
Translate translate = TranslateOptions.defaultInstance().service();
87+
```
88+
89+
Or you can explicitly set the API key as follows:
90+
```java
91+
Translate translate = TranslateOptions.builder().apiKey("myKey").service();
92+
```
93+
94+
#### Detecting language
95+
With Google Translate you can detect the language of some text. The service will provide you with
96+
the code of the detected language and a level of confidence.
97+
98+
Add the following import at the top of your file:
99+
100+
```java
101+
import com.google.cloud.translate.Detection;
102+
```
103+
104+
Then add the following code to detect the text's language:
105+
106+
```java
107+
String detectedLanguage = detection.language();
108+
```
109+
#### Translating text
110+
111+
Google translate allows you to translate some text. When translating one or more texts you can
112+
either provide the source language or let the service detect it for you.
113+
114+
Add the following imports at the top of your file:
115+
116+
```java
117+
import com.google.cloud.translate.Translate.TranslateOption;
118+
import com.google.cloud.translate.Translation;
119+
```
120+
121+
Then add the following code to translate a text (specifying its source language):
122+
123+
```java
124+
Translation translation = translate.translate(
125+
"World",
126+
TranslateOption.sourceLanguage("en"),
127+
TranslateOption.targetLanguage(detectedLanguage));
128+
```
129+
130+
#### Complete source code
131+
132+
In
133+
[DetectLanguageAndTranslate.java](../gcloud-java-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java)
134+
we put together all the code shown above into one program. The program assumes that a valid api key
135+
is available.
136+
137+
Troubleshooting
138+
---------------
139+
140+
To get help, follow the `gcloud-java` links in the `gcloud-*` [shared Troubleshooting document](https://github.com/GoogleCloudPlatform/gcloud-common/blob/master/troubleshooting/readme.md#troubleshooting).
141+
142+
Java Versions
143+
-------------
144+
145+
Java 7 or above is required for using this client.
146+
147+
Testing
148+
-------
149+
150+
This library has tools to help make tests for code using Cloud Translate.
151+
152+
See [TESTING] to read more about testing.
153+
154+
Versioning
155+
----------
156+
157+
This library follows [Semantic Versioning](http://semver.org/).
158+
159+
It is currently in major version zero (``0.y.z``), which means that anything
160+
may change at any time and the public API should not be considered
161+
stable.
162+
163+
Contributing
164+
------------
165+
166+
Contributions to this library are always welcome and highly encouraged.
167+
168+
See `gcloud-java`'s [CONTRIBUTING] documentation and the `gcloud-*` [shared documentation](https://github.com/GoogleCloudPlatform/gcloud-common/blob/master/contributing/readme.md#how-to-contribute-to-gcloud) for more information on how to get started.
169+
170+
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information.
171+
172+
License
173+
-------
174+
175+
Apache 2.0 - See [LICENSE] for more information.
176+
177+
[CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md
178+
[code-of-conduct]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CODE_OF_CONDUCT.md#contributor-code-of-conduct
179+
[LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE
180+
[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md#testing-code-that-uses-translate
181+
[cloud-platform]: https://cloud.google.com/
182+
183+
[google-translate]: https://cloud.google.com/translate/
184+
[google-translate-docs]: https://cloud.google.com/translate/docs/
185+
[translate-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/translate/package-summary.html

‎gcloud-java-translate/src/main/java/com/google/cloud/translate/package-info.java‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/**
18+
* A client to Google Translate.
19+
*
20+
* <p>Here's a simple usage example for using gcloud-java. This example shows how to detect the
21+
* language of some text and how to translate some text. The example assumes that the
22+
* {@code GOOGLE_API_KEY} is set and contains a valid API key. Alternatively, you can use
23+
* {@link com.google.cloud.translate.TranslateOptions.Builder#apiKey(java.lang.String)} to set the
24+
* API key. For the complete source code see
25+
* <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java">
26+
* DetectLanguageAndTranslate.java</a>.
27+
* <pre> {@code
28+
* Translate translate = TranslateOptions.defaultInstance().service();
29+
*
30+
* Detection detection = translate.detect("Hola");
31+
* String detectedLanguage = detection.language();
32+
*
33+
* Translation translation = translate.translate(
34+
* "World",
35+
* TranslateOption.sourceLanguage("en"),
36+
* TranslateOption.targetLanguage(detectedLanguage));
37+
*
38+
* System.out.printf("Hola %s%n", translation.translatedText());
39+
* }</pre>
40+
*/
41+
package com.google.cloud.translate;

‎pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -402,15 +402,15 @@
402402
</group>
403403
<group>
404404
<title>Test helpers packages</title>
405-
<packages>com.google.cloud.bigquery.testing:com.google.cloud.compute.testing:com.google.cloud.datastore.testing:com.google.cloud.dns.testing:com.google.cloud.logging.testing:com.google.cloud.pubsub.testing:com.google.cloud.resourcemanager.testing:com.google.cloud.storage.testing</packages>
405+
<packages>com.google.cloud.bigquery.testing:com.google.cloud.compute.testing:com.google.cloud.datastore.testing:com.google.cloud.dns.testing:com.google.cloud.logging.testing:com.google.cloud.pubsub.testing:com.google.cloud.resourcemanager.testing:com.google.cloud.storage.testing:com.google.cloud.translate.testing</packages>
406406
</group>
407407
<group>
408408
<title>Example packages</title>
409409
<packages>com.google.cloud.examples.*:com.google.cloud.nio.examples</packages>
410410
</group>
411411
<group>
412412
<title>SPI packages</title>
413-
<packages>com.google.cloud.spi:com.google.cloud.bigquery.spi:com.google.cloud.compute.spi:com.google.cloud.datastore.spi:com.google.cloud.dns.spi:com.google.cloud.logging.spi:com.google.cloud.logging.spi.*:com.google.cloud.pubsub.spi:com.google.cloud.pubsub.spi.*:com.google.cloud.resourcemanager.spi:com.google.cloud.storage.spi</packages>
413+
<packages>com.google.cloud.spi:com.google.cloud.bigquery.spi:com.google.cloud.compute.spi:com.google.cloud.datastore.spi:com.google.cloud.dns.spi:com.google.cloud.logging.spi:com.google.cloud.logging.spi.*:com.google.cloud.pubsub.spi:com.google.cloud.pubsub.spi.*:com.google.cloud.resourcemanager.spi:com.google.cloud.storage.spi:com.google.cloud.translate.spi</packages>
414414
</group>
415415
</groups>
416416
</configuration>

0 commit comments

Comments
 (0)