Download now and start building an interactive translation workflow with the DeepL.NET Official Library for the DeepL Translation API on GitHub. This package delivers an interactive experience for developers, with adapters that connect to DeepL and produce results quickly, in a standard workflow and seamless integration.
Use it to create translations in multiple formats and download the library to accelerate your projects with a clean API surface and interactive examples.
Here you will find current code, defined interfaces, and a standard set of adapters to connect your app with DeepL and deliver reliable translations.
The library provides seamless integration, with simple setup, formats for outputs, and results you can rely on in production.
There are practical examples, best-practice snippets, and clear guidance on how to provide robust localization flows; you can download and test quickly. Here is a current roadmap on the GitHub page to help you plan.
In practice, cela provides a minimal surface area for common tasks and helps you stay focused on business logic rather than boilerplate.
Access the library on GitHub to explore adapters, with support for multiple platforms, and to review formats supported by the API. The current codebase defines a clear standard, with measured performance, deterministic outcomes, and straightforward download steps.
DeepL.NET Official Library for the DeepL Translation API
Install the DeepL.NET Official Library from NuGet or download the sample, then run an example to verify translations from the DeepL Translation API. This library delivers a standard, seamless workflow with a defined API surface and ausgezeichnet performance on supported runtimes. Use the directive --help to explore options, and rely on features for translations, language detection, and batch requests. Try deepl-mock for local testing, and target monomac or tizen40 to cover macOS and Tizen environments. There is robust support for some texts and multiple sourcelanguages; you can download projects that demonstrate the end-to-end flow.
Getting started
Download the NuGet package, initialize the client with your API key, and call TranslateAsync with some texts and a defined sourcelanguages list. The example shows a single request returning translations and detected languages; use --help to inspect parameters and error handling. The library supports current versions and provides a straightforward path to production, with a focus on ease of use and testability.
Advanced usage
Define a custom translation pipeline with advanced options: set sourcelanguages, target languages, enable glossary support if available, adjust timeouts, and execute requests in parallel. The deepl-mock can drive test scenarios, and you can run tests for some texts to validate behavior. The API provides access to translations and the corresponding detected languages, and you can download and reuse example data. For cross-platform projects, ensure you build against the correct runtime (monomac on macOS, tizen40 on Tizen) and leverage the library features to provide reliable translations in production environments.
Get an authentication key and configure credentials for DeepL.NET
Obtain your API key from the DeepL Pro API dashboard and store it securely in your environment or secret store. Then initialize the DeepL.NET client with that key to enable translations for your projects.
- Acquire and store key: Sign in to the DeepL Pro API dashboard, generate an API key, and copy it. Save it as an environment variable DEEPL_AUTH_KEY or in a secure secret store. This keeps files in your repository free of credentials.
- Platform-specific storage: For xamarinmac and other platforms, prefer secure storage (Keychain on macOS/iOS, Credential Vault on Windows). During local tests you can rely on a deepl-mock setup to validate the integration without contacting production endpoints.
- Initialize client and set user-agent: Create a DeepL.NET client instance with the key and configure a descriptive user-agent string that reflects your platform and app name (for example: MyApp/1.0 (xamarinmac)). This helps monitoring and troubleshooting at the API level.
- Glossary and terminology: If you use glossaries, load glossarylanguages from the glossarylanguages source and attach to translation requests. This preserves domain terms in texts and maintains consistency across translations.
- Texts and files: The library supports translating simple texts and uploading files for batch processing. Use a clear project structure with separate tests and integration projects to keep credentials isolated from production code.
- Formality and language settings: For french translations, configure formality to match your target audience (formal vs informal) and align glossary content with your domain style. Use standard parameter sets and verify consistency with your glossary data.
- Versions and compatibility: Check the library versions against the API version you target. Align your integration in projects with the latest DeepL API changes, and adjust code paths accordingly. After updating, run a verification workflow in your tests.
- Testing strategy: Use deepl-mock for unit tests to validate request construction, parameter binding, and glossary usage before hitting real endpoints. Create dedicated tests and projects to cover translations, glossary interactions, and file-based workflows.
- Command and validation: Use the command line to inspect configuration and confirm the credential flow. Ensure the client reads the key at startup and that translations proceed without authentication errors.
Install and build from source: prerequisites, build commands, and troubleshooting tips
Clone the repo and install the prerequisites, then execute the build to verify integration in your window. Recommended commands: git clone https://github.com/hellotxt/deepls-net.git; cd deepls-net; git fetch --tags; git checkout releases/latest; dotnet restore; dotnet build -c Release. This approach keeps you aligned with the default workflow and gives a seamless path from source to testing with deepls.
Prerequisites
Install the .NET SDK 8.x or newer and confirm a compatible framework set is present. Ensure git is installed and accessible in your environment, and that dotnet --version returns a supported runtime. For local testing, run a mock-server to simulate the API and point translatoroptions to http://localhost:
Build, test, and troubleshooting
Execute dotnet restore, dotnet build -c Release, and dotnet test to validate the build and test suite. If tests rely on a mock-server, ensure it runs on the configured port and that the base URL matches translatoroptions. Use input examples to verify that default translatoroptions return correct results, and inspect the output window for any computed values. If a failure mentions languagecodefrench or glossary descriptions, verify the glossary and language mappings in the repository from the glossary and glossarylanguages files.
If a build error appears about missing packages, run dotnet restore again and check your NuGet feeds. For environment issues, confirm the PATH includes dotnet and that you are executing commands from the project root. When tests fail due to network or API differences, adjust the mock-server settings, or switch to a known good release from releases to reproduce behavior. In case of port conflicts, stop the other service or reconfigure MOCK_SERVER_PORT and update the corresponding translatoroptions input.
If you discover a bug or a missing feature, create a commit on a feature branch and contribute a patch or a new test. Provide clear input, attach minimum reproducible steps, and reference hellotxt and deepls in your description. After pushing, open a pull request to review, attach logs, and share how the fix affects frameworks and which languages are affected. This collaborative process helps maintainers understand the implications and move from local experiments to a stable release.
Use adapters: list of currently supported adapters and how to select one
Install the DeepL.NET library from nuget and initialize in your environment. By default, the HTTP-based adapter handles online translations; for test runs, switch to the Mock adapter to verify behavior without network calls.
Currently available adapters are HTTP-based, Mock for test scenarios, File-based (reads input texts from a file), and Echo for debugging. Each adapter is provided to cover common needs: production translation, unit tests, file-driven workflows, and quick checks during development.
To select one, run --help to see which adapters are available, then set the setting in your configuration accordingly. For example, in code you can define setting.Adapter = AdapterType.Http; this choice is defined in the core configuration and applies to all subsequent calls. If you switch to Mock or File-based adapters, you can validate the behavior without touching live data.
Example input and flow: provide input texts array and a list of targetlanguages; the output contains translated texts for each target language. Use the provided example to test integration and verify that the translation results match expectations. If you need a quick test, the Echo adapter returns input as output, which helps verify the pipeline is wired correctly.
Environment considerations: ensure the install step uses nuget and that the environment variable or configuration file defines the default adapter. With advanced configuration, you can refresh the list of targetlanguages from the DeepL API and adjust input sources without restarting the application. The needs of your app dictate whether to use HTTP in production or Mock for tests; some teams prefer switching adapters during CI to validate behavior end-to-end, using await for async calls where appropriate.
In German locales, prompts may include geht in help text, reflecting localization while you navigate the adapter choices.
Make translations with DeepL.NET: request patterns, response handling, and error management
Start with the standard DeepL.NET workflow: create a client using the provided API key, then create a TranslationRequest and call TranslateAsync. The deepls library layer wraps this API neatly, and for a single hellotxt sentence, specify the target language and allow auto-detect of the source; for multiple items, use the batch path and map each translated result to its input. This approach delivers a reliable output quickly and scales across frameworks.
Request patterns: use either single-text or multiple-text modes. The request accepts a single string or an array; does this fit your workflow? Before sending, validate input that there is content. If you work with custom terminology, attach glossaries to enforce terms; leverage computed language codes when you generate target values. For testing, switch to deepl-mock to simulate responses; include sample inputs such as geht to verify language detection. Keep an eye on versions and frameworks to stay compatible.
Response handling: inspect the result and extract the translated content. The API returns a translated string or a collection when processing multiple items; there, correlate each translated item with its input by matching indices. When a translation appears, show the output in the UI or store it in a data store; if a translation exists for multiple targets, process each separately and gracefully handle missing items.
Error management: wrap calls in try-catch and differentiate between network, authentication, and quota errors. Retry transient failures with exponential backoff; if the API reports invalid credentials, handle the override path to refresh keys or prompt for re-authentication. Log diagnostic data about requests (avoiding sensitive content) and surface friendly messages to users. In development, use deepl-mock to keep feedback fast; monitor errors by their frameworks and versions, then adjust integration actions accordingly.
Platform notes: for cross‑platform integration, reuse the same request/response logic for frameworks including xamarinwatchos and tizen40. Provide a small adapter per platform and use override where necessary to handle IO or UI updates. The flow remains the same; their API surface should stay stable as you evolve versions and support multiple languages across actions and components.
Practical tips: bake a translation cake by combining custom glossaries, standard settings, and careful input handling. Build small, reusable functions that create and send requests, and use argument objects to keep calls clean. Use the output from a translation to drive UI updates, and keep both "hellotxt" samples and real data ready for testing. There there.
Automate development with GitHub Actions: CI, tests, and release workflow
Establish a standard CI that triggers on pushes and pull requests, validates the DeepL.NET Official Library alongside Yii2 samples, and runs tests with a deepl-mock fixture. Validate translations across targetlanguages and translatoroptions, including override and default setting variations. Execute builds and tests until green, giving maintainers clear feedback on code quality, packaging, and release readiness. Cela ensures consistent behavior across projects and protects de facto expectations for their users.
CI and tests on GitHub Actions
Create a workflow file that runs on ubuntu, macos, and windows runners to cover diverse environments. Use actions/checkout to fetch code, actions/setup-net, and actions/setup-php for Yii2 tests, plus a setup step for .NET runtimes. Run dotnet restore and dotnet test for the DeepL.NET library, and composer install followed by vendor/bin/phpunit for the Yii2 samples. Include a deepl-mock download step to avoid API calls in tests, then exercise targetlanguages with translatoroptions to verify behavior. Override test keys via GitHub secrets only in secure jobs, and structure jobs with needs to ensure the PHP and .NET stages run in the correct sequence. The workflow should expose --help output to validate CLI usage and confirm code paths across the library, their objects, and features.
| Step | Tool | Key Points | Notes |
|---|---|---|---|
| Checkout & Setup | GitHub Actions, actions/checkout, setup-dotnet, setup-php | Fetch code, prepare environments, install dependencies | Matrix: Ubuntu/macOS/Windows; PHP versions; .NET versions |
| Build & Test (DeepL.NET) | .NET, unit tests, deepl-mock | dotnet restore, dotnet test, validate exit codes | Use translatoroptions to cover standard and advanced modes |
| Test (Yii2) | PHP, Composer, PHPUnit | composer install, vendor/bin/phpunit | Download deepl-mock for test isolation before tests |
| Validation | CLI checks, --help | execute code paths, verify outputs | Ensure respects override and setting changes |
| Cleanup & Reporting | GitHub Actions artifacts, test results | store logs, summarize failures | Maintainers review results and plan fixes |
Release workflow and packaging
On tag or main merge, run dotnet pack to produce a NuGet package for the library and a Composer-ready bundle for sample projects. Publish artifacts only with a guarded release process, using a secure token from GitHub Secrets. Include release notes derived from conventional commits, and create a GitHub release automatically. Validate that the package name and codes align with supported targets, and verify binary compatibility against the object model and their features. Ensure the download of the latest deepls and deepl-mock variants to confirm compatibility before publishing. Maintainers can contribute by adding new targets, updating targetlanguages lists, and extending translatoroptions to cover adicional locales cela and others. The objective remains a reliable, repeatable release that users can download and integrate into their workflows.
| Step | Tool | Key Points | Notes |
|---|---|---|---|
| Pack & Release | .NET pack, NuGet, GitHub Release | build artifacts, versioning, release notes | Tag-based triggers; use GITHUB_TOKEN for pushes |
| Publish | NuGet, Composer registry | publish binaries and PHP packages | sign packages if required; ensure proper access rights |
| Validation post-release | CI checks, smoke tests | verify that deepls features and translatoroptions work after install | run a quick sample to confirm targetlanguages behavior |
