Skip to content

Commit 46af9fe

Browse files
dimitrystddimitrystd
committed
docs: Update README with detailed usage, features, and contribution guidelines
1 parent 54ece7f commit 46af9fe

1 file changed

Lines changed: 116 additions & 31 deletions

File tree

‎README.md‎

Lines changed: 116 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,137 @@
11
# Smartling Java API SDK
22

3-
Java SDK for integrating with the [Smartling API].
3+
[![Maven Central](https://img.shields.io/maven-central/v/com.smartling.api/smartling-api-sdk.svg)](https://central.sonatype.com/search?q=g%3Acom.smartling.api&smo=true&namespace=com.smartling.api)
4+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
45

5-
## Using this SDK
6+
The official Java SDK for the [Smartling Translation Management Platform](https://www.smartling.com). This library provides a type-safe, idiomatic Java interface to Smartling's REST APIs, enabling seamless integration of translation workflows into your applications.
67

7-
The Smartling API SDK is distributed via Maven Central and is compatible with JDK 1.7
8-
(Java 7) and up.
8+
## Features
9+
10+
- **Automatic OAuth 2.0 Management** - Built-in token acquisition, refresh, and secure credential handling
11+
- **Type-Safe API Clients** - Strongly-typed interfaces with comprehensive error handling
12+
- **Multi-Module Architecture** - Include only the API modules you need to minimize dependencies
13+
- **Production Ready** - Battle-tested by hundreds of enterprise integrations with comprehensive test coverage
14+
- **Modern Java Support** - Built with RESTEasy, Jackson, and Apache HttpClient
15+
16+
## Requirements
17+
18+
- **Java 8 or higher** (JDK 1.8+)
19+
- Maven 3.6+ or Gradle 5.0+
20+
21+
### Core Dependencies
22+
23+
- RESTEasy 4.7.10 (JAX-RS client implementation)
24+
- Jackson 2.15.4 (JSON serialization)
25+
- Apache HttpClient 4.5.14 (HTTP transport)
26+
- SLF4J 1.7.28 (Logging facade)
27+
28+
## Installation
929

1030
### Maven
1131

12-
Add the SDK to your dependencies:
32+
Add the SDK to your `pom.xml`:
1333

14-
<dependencies>
15-
<dependency>
16-
<groupId>com.smartling.api</groupId>
17-
<artifactId>smartling-api-sdk</artifactId>
18-
<version>${version}</version>
19-
</dependency>
20-
</dependency>
34+
```xml
35+
<dependency>
36+
<groupId>com.smartling.api</groupId>
37+
<artifactId>smartling-api-sdk</artifactId>
38+
<version>1.26.2</version>
39+
</dependency>
40+
```
2141

2242
### Gradle
2343

24-
Add the SDK to your dependencies:
25-
26-
dependencies {
27-
implementation "com.smartling.api:smartling-api-sdk:${version}"
44+
Add the SDK to your `build.gradle`:
45+
46+
```gradle
47+
dependencies {
48+
implementation 'com.smartling.api:smartling-api-sdk:1.26.2'
49+
}
50+
```
51+
52+
## Quick Start
53+
54+
The SDK automatically manages OAuth 2.0 authentication when you provide your API credentials:
55+
56+
```java
57+
import com.smartling.api.files.v2.FilesApi;
58+
import com.smartling.api.files.v2.FilesApiFactory;
59+
import com.smartling.api.v2.authentication.AuthenticationApi;
60+
import com.smartling.api.v2.authentication.AuthenticationApiFactory;
61+
import com.smartling.api.v2.client.ClientFactory;
62+
import com.smartling.api.v2.client.DefaultClientConfiguration;
63+
import com.smartling.api.v2.client.auth.Authenticator;
64+
import com.smartling.api.v2.client.auth.BearerAuthSecretFilter;
65+
66+
public class SmartlingExample {
67+
public static void main(String[] args) {
68+
String userIdentifier = "YOUR_USER_IDENTIFIER";
69+
String userSecret = "YOUR_USER_SECRET";
70+
71+
// Create a factory for building API clients
72+
DefaultClientConfiguration clientConfiguration = DefaultClientConfiguration.builder().build();
73+
ClientFactory clientFactory = new ClientFactory();
74+
75+
// Create the authenticator to be used by subsequent API calls
76+
AuthenticationApi authenticationApi = new AuthenticationApiFactory(clientFactory).buildApi(clientConfiguration);
77+
Authenticator authenticator = new Authenticator(userIdentifier, userSecret, authenticationApi);
78+
79+
// Create files API client
80+
FilesApi filesApi = new FilesApiFactory(clientFactory)
81+
.buildApi(new BearerAuthSecretFilter(authenticator), clientConfiguration);
82+
83+
// Use the API client
84+
// ...
2885
}
86+
}
87+
```
2988

30-
### Initialize the SDK
89+
For detailed examples and tutorials, visit our [samples repository](https://github.com/Smartling/smartling-samples/).
3190

32-
The Smartling SDK manages OAuth 2 authentication automatically when you provide
33-
a API v2.0 identifier and a user secret to the API factory.
91+
## Version Support
3492

35-
SmartlingApi createSmartlingApi(String userIdentifier, String userSecret)
36-
{
37-
return new SmartlingApiFactory()
38-
.build(userIdentifier, userSecret);
39-
}
93+
### Current Version (1.x)
94+
95+
- **Minimum Java Version**: Java 8 (JDK 1.8)
96+
- **End of Support**: December 1, 2026
97+
- **Status**: Stable and production-ready
98+
99+
### Upcoming Version (2.x)
100+
101+
- **Minimum Java Version**: Java 17 (JDK 17)
102+
- **Release**: Coming soon
103+
- **Migration Guide**: Will be provided upon release
104+
105+
We recommend planning your migration to Java 17+ to ensure continued support beyond 2026.
106+
107+
## Documentation
108+
109+
- **[API Reference](https://api-reference.smartling.com/)** - Complete REST API documentation
110+
- **[Java SDK Guide](https://help.smartling.com/hc/en-us/articles/4403912351131-Java-SDK)** - SDK-specific documentation and best practices
111+
- **[Help Center](https://help.smartling.com/hc/en-us/sections/1260801854870-Smartling-API)** - API guides and tutorials
112+
- **[Code Samples](https://github.com/Smartling/smartling-samples/)** - Working examples and integration patterns
113+
114+
## Support
115+
116+
- **Bug Reports**: [GitHub Issues](https://github.com/Smartling/java-api-sdk/issues)
117+
- **Feature Requests**: [GitHub Issues](https://github.com/Smartling/java-api-sdk/issues)
118+
- **Security Issues**: Please report privately to security@smartling.com
40119

41120
## Contributing
42121

43-
Open an issue on this repository to discuss any planned changes other than bug fixes
44-
with Smartling's maintainers.
122+
We welcome contributions from the community! Before submitting significant changes:
123+
124+
1. Open an issue to discuss your proposed changes with the maintainers
125+
2. Fork the repository and create a feature branch
126+
3. Ensure all tests pass and add new tests for your changes
127+
4. Submit a pull request with a clear description of your changes
128+
129+
For Smartling employees, please refer to the internal wiki for contribution guidelines.
130+
131+
## License
45132

46-
Fork this repository and create a pull request with your proposed changes. Your pull
47-
request must pass all automated tests before it will be considered for inclusion.
133+
This project is licensed under the [Apache License 2.0](LICENSE).
48134

49-
Smartling developers should refer to the wiki for instructions on contributing to this
50-
SDK.
135+
---
51136

52-
[Smartling API]: https://api-reference.smartling.com/
137+
**Smartling** | [Website](https://www.smartling.com) | [API Documentation](https://api-reference.smartling.com/)

0 commit comments

Comments
 (0)