Google Cloud Translation setup

The google-cloud-translation provider wraps Google Cloud Translation v2. It authenticates with an API key and supports plain-text and HTML payloads. This is the recommended provider for production.

1. Enable the Cloud Translation API

1. Open the Cloud Translation API page in a Google Cloud project that has billing enabled.
2. Click Enable.

2. Create an API key

1. Open APIs & Services → Credentials.
2. Click Create credentials → API key.
3. Copy the key (it starts with AIza).
4. Restrict the key. A leaked unrestricted API key can be used against any Google API on the project, so this step matters:
   • Under Application restrictions, leave None unless your server has a fixed outbound IP you can lock to.
   • Under API restrictions, choose Restrict key and select only Cloud Translation API.

3. Add the key to appsettings.json

The provider reads the API key from Umbraco:UmbracoTranslator:GoogleCloud:ApiKey. Add the section and flip the default provider alias:

{
  "Umbraco": {
    "UmbracoTranslator": {
      "DefaultProviderAlias": "google-cloud-translation",
      "TranslateBlockGridContents": true,
      "SkipPropertyEditorAliases": [],
      "GoogleCloud": {
        "ApiKey": "AIza..."
      }
    }
  }
}

For environment-specific keys, override in appsettings.Production.json or pass the value via an environment variable: Umbraco__UmbracoTranslator__GoogleCloud__ApiKey.

Never commit the API key. Use dotnet user-secrets locally and your hosting platform's secret manager in production.

4. Restart the site

Options are reloaded on the next request, but a restart is the simplest way to confirm the provider is picked up. Open Settings → Translator license; the activate / translate flow now uses Google for every call that doesn't override providerAlias.

Format handling

UmbracoTranslator classifies each property by editor alias before calling the provider. The Google provider maps those formats as follows:

• PlainText → Google text. Used for textstring, textarea, and Block Grid string values.
• Html → Google html. Used for rich text and Block Grid rich-text editors. Google preserves tags and attributes natively, so formatting survives the round-trip.
• Markdown → sent as text. Content is translated, but Markdown syntax characters (#, *, _, []()) can shift around. If structure matters, store the source as HTML instead.

Costs and quotas

• Google bills per character of source text. UmbracoTranslator's license counts source words against your allowance — these are different units.
• Per-project quotas are visible in the Google Cloud Console under IAM & Admin → Quotas.
• The provider creates one TranslationClient per unique API key value and caches it. Rotating the key picks up on the next request automatically — no restart required.

Troubleshooting

• "GoogleCloudTranslationProvider requires an API key" on the first translation: the ApiKey value is empty or whitespace. Double-check the appsettings.json path (Umbraco:UmbracoTranslator:GoogleCloud:ApiKey) and casing.
• 403 from Google: the API isn't enabled on the project, or the API key restriction excludes Cloud Translation.
• 400 "Invalid value": the source or target culture isn't supported. Google uses BCP-47 codes (e.g. en, nl); Umbraco passes full culture codes like en-US and Google normalizes them, but exotic culture variants can fail.

Use a different provider

To plug in DeepL, OpenAI, or anything else, implement ITranslationProvider in your own assembly and register it in DI:

builder.Services.AddSingleton<ITranslationProvider, MyDeepLProvider>();

Set DefaultProviderAlias to the new provider's Alias string and you're done. Providers can coexist — the API request body accepts an optional providerAlias override per call.