The Smartling connector exposes a scoped REST API under /api/smartling.translation that the connector calls to read and write localizable content.

This article will guide you through installing and configuring Episerver 13 (.NET 10).

If you are working with Episerver 12 (.NET Core 5), read this documentation.
If you are working with Episerver 11 (.NET Framework 4.x.x), read this documentation.

Episerver is now known as Optimizely. For consistency, this documentation and the Smartling interface refer to this software as Episerver.

Please note that this Connector is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

Requirements

All versions of the plugin are available on the Smartling.Translation NuGet package page.

Step 1: Register an OpenID Connect client

Smartling authenticates with the client_credentials grant and needs the smartling_api scope. Install EPiServer.OpenIDConnect, then register the client in your service configuration:

using EPiServer.OpenIDConnect;
using Smartling.Translation.Core.Configuration;

services.AddOpenIDConnect<TUser>(
    useDevelopmentCertificate: true,   // development only
    createSchema: true,
    configureOptions: options =>
    {
        options.Applications.Add(new OpenIDConnectApplication
        {
            ClientId     = "<smartling_client_id>",
            ClientSecret = "<smartling_client_secret>",
            Scopes       = { SmartlingApiOptionsDefaults.Scope }
        });
    });

• TUser is the ASP.NET Identity user type your site registers with AddCmsAspNetIdentity<TUser>().
• createSchema: true creates the OpenIddict tables on first start.
• In production, replace useDevelopmentCertificate with the overload that takes explicit signing and encryption certificates.

Step 2: Initialize the Smartling API

Register the Smartling API and enable CORS, which the EPiServer OpenID Connect token controller requires:

services.AddSmartlingApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
services.AddCors();   // required by EPiServer's OpenID Connect token controller

Then, in your request pipeline:

app.UseRouting();
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
    endpoints.MapContent();
    endpoints.MapControllers();   // required
});

With minimal hosting, call app.MapControllers() alongside app.MapContent().

Important: Both additions are required, and each fails in a way that does not point at its cause. Without MapControllers(), every Smartling endpoint and the OAuth token endpoint return 404, because MapContent() does not create MVC's attribute-routed endpoint data source. Without CORS, the token endpoint returns 500 with "contains CORS metadata, but a middleware was not found that supports CORS".

Step 3: Enable logging

{
  "Logging": {
    "LogLevel": {
      "Smartling.Translation": "Information"
    }
  }
}

.NET's built-in log providers do not write files. To route these logs to a separate file, add a file-capable provider such as Serilog.

Step 4: Verify

Request an access token, then use it to call the Smartling API:

curl -sS -X POST 'https://<your-cms-host>/api/episerver/connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<smartling_client_id>' \
  -d 'client_secret=<smartling_client_secret>' \
  -d 'scope=smartling_api'

curl -sS 'https://<your-cms-host>/api/smartling.translation/dictionary/content-types?filter=page' \
  -H 'Authorization: Bearer <access_token>'

The second call returns your page content types. Use filter=block, filter=media, or filter=catalog for the others.

Important: The filter parameter is required. An omitted or misspelled filter matches nothing and returns an empty list, not everything.

Endpoints return HTTP 200 and report failure in the body's code field, so checking the status code alone will mislead you.

Next steps

When installation is complete, provide your Smartling Solutions Architect with the following so Smartling can complete configuration of the connector:

• API URL – the base URL of your Episerver instance, e.g. https://your.episerver.domain
• Client ID – created in Step 1
• Client Secret – created in Step 1

IP Whitelisting

If you would like to limit access to Smartling API or provide access to your dev/sandbox environment you can whitelist the following IPs:

• 52.200.226.107
• 52.200.205.55
• 52.86.212.212
• 52.87.14.187
• 54.243.240.47

Smartling integration will access to the following endpoints:

• <schema>://<epi-server-host>:<port>/api/episerver/connect/token
• <schema>://<epi-server-host>:<port>/<protectedVirtualPath>/smartling.translation/*

Connecting Episerver to Smartling

1. Create an Episerver Connector project type in your Smartling Account.
2. From within this project, click Settings > Episerver Settings.
3. Click Connect to Episerver.
4. Choose to connect by OAuth login (Client ID and secret). The following URL settings are used for authentication:
   • apiUrl (mandatory): the URL used to access Episerver in general. Usually this is just a host, e.g. http://172.30.21.102/.
   • authApiUrl (optional): a path to the auth endpoint, without a host. Default value is /api/episerver/auth/token. The connector concatenates apiUrl with authApiUrl to get the full authentication endpoint.
   • apiVirtualPath (optional): Episerver uses the /episerver virtual path by default, so the hosted connector may use something like http://172.30.21.102/episerver/smartling.translation/pages/13 to get content. To change this, give Smartling a new value, e.g. /api, and the connector will build the content URL with that segment instead, e.g. http://172.30.21.102/api/smartling.translation/pages/13.
   • Important note: Smartling's Episerver installation uses the /api virtual path by default. This can be changed via the plugin API in your Episerver customer development project.
   • basePreviewUrl (optional): the connector makes an HTTP request to fetch preview HTML, and by default uses apiUrl for this since it doesn't otherwise know the URL of your Episerver instance. This works for simple site setups, but if your site has separate Author and Publish Episerver instances, set basePreviewUrl to the Author instance – the connector needs Author, not Publish.
   • sslVerificationMode (optional): if your Author instance has an invalid SSL certificate (for example, because access to it is restricted via IP allowlisting), set sslVerificationMode to DISABLED so the hosted connector skips SSL certificate verification for Episerver.
5. Click Connect to Episerver to complete the connection, or cancel to exit the menu.
6. Click Allow to authorize the Smartling Episerver Connector.

Your Episerver instance will now be connected to your Smartling project. Now you're ready to configure your Episerver Connector.