class AnalyticsTracker {
  // ========================
  //   Globals & Constants
  // ========================
  static globalState = {
    isSearchListenerAdded: false,
  };

  static API_ENDPOINTS = {
    PRO: "api.deepl.com",
    FREE: "api-free.deepl.com"
  }

  static PAGE_ID_DEVELOPERS_WEBSITE_DOCUMENTATION = 4001;
  static PAGE_ID_DEVELOPERS_WEBSITE_API_REFERENCE = 4002;

  static EVENT_ID_PAGEVIEW = 1;
  static EVENT_ID_NETWORK_REQUEST = 5000;
  static EVENT_ID_SEARCH_INPUT = 5001; // TODO change this after DAP update

  static isProdStage = window.location.hostname === "developers.deepl.com";
  static statisticsUrl = this.isProdStage ? 
    "https://s.deepl.com/web/statistics"
    : "https://s.deepl.dev/web/statistics"

  // ========================
  //   Cookie Helper Inner Class
  // ========================
  static CookieHelper = class {
    static DAP_UID_KEY = 'dapUid';
    static DAP_SID_KEY = 'dapSid';
    
    static YEAR_IN_MINUTES = 60 * 24 * 30 * 12;
    static SID_TTL_MINUTES = 30;

    static getCookieItem(cookieName) {
      if (typeof window === 'undefined') {
        throw new Error('Error occurs when you are going to use a browser-specific code on server-side or other way around. Please check your code logic.');
      }
      const cookies = document.cookie.split('; ') || [];
      const cookie = cookies.find(c => c.startsWith(`${cookieName}=`)) || '';
      const value = cookie.split('=').at(1);
      return value ? decodeURIComponent(value) : value;
    }

    static setCookieItem(cookieName, cookieValue, expiresInMinutes = 0) {
      if (typeof window === 'undefined') {
        throw new Error('Error occurs when you are going to use a browser-specific code on server-side or other way around. Please check your code logic.');
      }
      const cookieValueToStore = (
        typeof cookieValue === 'string' || typeof cookieValue === 'number'
          ? cookieValue
          : JSON.stringify(cookieValue)
      );
      let expireString = '';
      if (expiresInMinutes) {
        const date = new Date();
        const expiresInMilliseconds = expiresInMinutes * 60 * 1000;
        date.setTime(date.getTime() + expiresInMilliseconds);
        expireString = `; expires=${date.toUTCString()}`;
      }
      const domain = AnalyticsTracker.isProdStage ? '.deepl.com' : window.location.hostname;
      const domainString = `; domain=${domain}`;
      const secure = '; secure';
      document.cookie = `${cookieName}=${encodeURIComponent(cookieValueToStore)}${domainString}; path=/${expireString}; samesite=lax${secure}`;
    }

    static mkUUID() {
      if (typeof window === 'undefined') {
        return '';
      }
      if (!Object.prototype.hasOwnProperty.call(window, 'crypto')) {
        return '';
      }
      if (typeof window.crypto.randomUUID === 'function') {
        return window.crypto.randomUUID();
      }
      return [1e7, -1e3, -4e3, -8e3, -1e11].join('').replace(/[018]/g, c =>
        (parseInt(c, 10) ^ (window.crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (parseInt(c, 10) / 4)))).toString(16));
    }

    static getUid() {
      let uid = this.getCookieItem(this.DAP_UID_KEY);
      if (uid === undefined) {
        this.setCookieItem(
          this.DAP_UID_KEY,
          this.mkUUID(),
          this.YEAR_IN_MINUTES
        );
      }
      uid = this.getCookieItem(this.DAP_UID_KEY);
      return uid;
    }

    static getSid() {
      let sidCookie = this.getCookieItem(this.DAP_SID_KEY);
      let sidObj;
      if (sidCookie) {
        try {
          sidObj = JSON.parse(sidCookie);
        } catch {
          sidObj = null;
        }
      }
      const now = Date.now();
      if (sidObj && sidObj.sid && sidObj.lastUpdate) {
        // SID exists already
        if (now - sidObj.lastUpdate > this.SID_TTL_MINUTES * 60 * 1000) {
          sidObj = {
            sid: this.mkUUID(),
            lastUpdate: now
          };
        } else {
          sidObj = {
            ...sidObj,
            lastUpdate: now
          };
        }
      } else {
        // SID does not exist
        sidObj = {
          sid: this.mkUUID(),
          lastUpdate: now
        };
      }
      this.setCookieItem(this.DAP_SID_KEY, JSON.stringify(sidObj), this.SID_TTL_MINUTES);
      return sidObj.sid;
    }
  };

  // ========================
  //   Request Helper Inner Class
  // ========================
  static RequestHelper = class {
    static async baseRequest(url, getPayload) {
      const payload = getPayload();
      try {
        const response = await fetch(
          url,
          {
            headers: {
              "content-type": "application/json",
            },
            body: JSON.stringify(payload),
            method: "POST",
          }
        );
        const data = await response.json();
        // console.log('Fetched data: ', data);
        return data;
      } catch (error) {
        console.error('Fetch error: ', error);
      }
    }

    static getPageId() {
      const pathname = window.location.pathname;
      const secondSlash = pathname.indexOf("/", 1);
      const firstSubpath = secondSlash !== -1 ? pathname.substring(0, secondSlash) : pathname;
      switch (firstSubpath) {
        case "/docs":
          return AnalyticsTracker.PAGE_ID_DEVELOPERS_WEBSITE_DOCUMENTATION;
        case "/api-reference":
          return AnalyticsTracker.PAGE_ID_DEVELOPERS_WEBSITE_API_REFERENCE;
        default:
          return 0;
      }
    }

    static requestToDAP(eventId, extraFields) {
      // console.log(`[${eventId}]: ${JSON.stringify(extraFields)}`); 
      
      this.baseRequest(
        AnalyticsTracker.statisticsUrl,
        () => ({
          instanceId: AnalyticsTracker.CookieHelper.getUid(),
          sessionId: AnalyticsTracker.CookieHelper.getSid(),
          eventId: eventId,
          pageId: this.getPageId(),
          userAgent: navigator.userAgent,
          interfaceLanguage: navigator.language,
          screenInfo: {
            widthCssPixel: window.screen.width,
            heightCssPixel: window.screen.height,
            viewportWidthCssPixel: window.innerWidth,
            viewportHeightCssPixel: window.innerHeight,
            devicePixelRatio: window.devicePixelRatio
          },
          url: `${window.location.origin}${window.location.pathname}${window.location.search}`,
          ...extraFields
        })
      );
    }
  };

  // ========================
  //   Track Page Navigation Inner Class
  // ========================
  static PageNavigationTracker = class {
    static navigationState = {
      lastTrackedUrl: null
    }

    static sendPageview() {
      AnalyticsTracker.RequestHelper.requestToDAP(
        AnalyticsTracker.EVENT_ID_PAGEVIEW, 
        {
          pageviewData: {
            referrer: document.referrer,
            pageVariant: 0,
          }
        }
      );
    }

    static sendPageviewDeduped() {
      const currentUrl = window.location.href;
      if (currentUrl === this.navigationState.lastTrackedUrl) return; // Skip duplicate
      this.navigationState.lastTrackedUrl = currentUrl;
      this.sendPageview(); 
    }

    static setupNavigationTrackers() {
      const _pushState = history.pushState;
      const _replaceState = history.replaceState;

      history.pushState = function (...args) {
        _pushState.apply(this, args);
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      };

      history.replaceState = function (...args) {
        _replaceState.apply(this, args);
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      };

      window.addEventListener('popstate', () => {
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      });

      window.addEventListener('hashchange', () => {
        AnalyticsTracker.PageNavigationTracker.sendPageviewDeduped();
      });

      this.sendPageviewDeduped();
    }
  };

  // ========================
  //   Network Request Tracking Inner Class
  // ========================
  static NetworkRequestTracker = class {
    static sendOutgoingNetworkResponse(statusCode, apiUrl) {
      AnalyticsTracker.RequestHelper.requestToDAP(
        AnalyticsTracker.EVENT_ID_NETWORK_REQUEST, 
        {
          developersWebsiteNetworkData: {
            statusCode,
            apiUrl 
          }
        }
      );
    }

    static setupNetworkRequestTracking() {
      const originalOpen = XMLHttpRequest.prototype.open;
      const originalSend = XMLHttpRequest.prototype.send;

      XMLHttpRequest.prototype.open = function(method, url) {
        const xhr = this;
        xhr._recordedUrl = url;
        return originalOpen.apply(xhr, arguments);
      };

      XMLHttpRequest.prototype.send = function(body) {
        // Note: we cannot log the url, request body, or response body because of sensitive info
        const xhr = this;
        const originalOnReadyStateChange = xhr.onreadystatechange;
        xhr.onreadystatechange = function() {
          if (xhr.readyState === 4) { // DONE
            
            const urlObj = new URL(xhr._recordedUrl)
            if (
              urlObj.hostname === AnalyticsTracker.API_ENDPOINTS.PRO ||
              urlObj.hostname === AnalyticsTracker.API_ENDPOINTS.FREE
            ) {
              // Prune out any custom query params which could be input data
              const prunedUrl = `${urlObj.origin}${urlObj.pathname}`

              AnalyticsTracker.NetworkRequestTracker.sendOutgoingNetworkResponse(
                xhr.status,
                prunedUrl
              );
            }
            else {
              // do nothing for other requests
            }
          }
          if (originalOnReadyStateChange) {
            originalOnReadyStateChange.apply(xhr, arguments);
          }
        };
        return originalSend.apply(xhr, arguments);
      };
    }
  };

  // ========================
  //   Search Input Tracking Inner Class
  // ========================
  static SearchInputTracker = class {
    static InputClassification = {
      Partial: 'Partial',
      Submitted: 'Submitted', // Not implemented yet
      AiAssistant: 'AiAssistant'
    };

    static filteredHostnames = ['leaves.mintlify.com'];

    static sendSearchInput(searchInputText, classification) {
      AnalyticsTracker.RequestHelper.requestToDAP(
        AnalyticsTracker.EVENT_ID_SEARCH_INPUT, 
        {
          searchInputText,
          classification
        }
      );
    }

    static addSearchInputListener() {
      const searchInput = document.getElementById('search-input');
      if (!AnalyticsTracker.globalState.isSearchListenerAdded && searchInput) {
        searchInput.addEventListener('input', (event) => {
          const inputText = event.target.value;
          this.sendSearchInput(inputText, this.InputClassification.Partial);
        });
        AnalyticsTracker.globalState.isSearchListenerAdded = true;
      }
    }

    static removeSearchInputListener() {
      const searchInput = document.getElementById('search-input');
      if (AnalyticsTracker.globalState.isSearchListenerAdded && !searchInput) {
        AnalyticsTracker.globalState.isSearchListenerAdded = false;
      }
    }

    static setupSearchInputTracking() {
      // As the user is typing
      const observer = new MutationObserver((mutations) => {
        mutations.forEach((mutation) => {
          if (mutation.addedNodes.length) {
            this.addSearchInputListener();
          }
          if (mutation.removedNodes.length) {
            this.removeSearchInputListener();
          }
        });
      });
      observer.observe(document.body, { childList: true, subtree: true });
      this.addSearchInputListener();

      // When a user submits to the AI Assistant
      const originalFetch = window.fetch;
      window.fetch = async (...args) => {
        try {
          const url = typeof args[0] === 'string' ? args[0] : args[0].url;
          const requestHostname = new URL(url).hostname;
          if (this.filteredHostnames.includes(requestHostname)) {
            this.sendSearchInput(args[1].body, this.InputClassification.AiAssistant);
          }
          return originalFetch(...args);;
        } catch (error) {
          return originalFetch(...args);
        }
      };
    }
  };

  // ========================
  //   Initialization
  // ========================
  static init() {
    this.PageNavigationTracker.setupNavigationTrackers();
    this.NetworkRequestTracker.setupNetworkRequestTracking();
    // this.SearchInputTracker.setupSearchInputTracking(); // Disable this for now
  }
}

// Initialize on page load
AnalyticsTracker.init();


Translate text

Additional context that can influence a translation but is not translated itself.

Characters included in the `context` parameter will not be counted toward billing.

Sets whether the translated text should lean towards formal or informal language.
This feature is only available for certain target languages. Setting this parameter 
with a target language that does not support formality will fail, unless one of the 
`prefer_...` options are used.
Possible options are:
  * `default` (default)
  * `more` - for a more formal language
  * `less` - for a more informal language
  * `prefer_more` - for a more formal language if available, otherwise fallback to default formality
  * `prefer_less` - for a more informal language if available, otherwise fallback to default formality

Specifies which DeepL model should be used for translation.

Disable the automatic detection of XML structure by setting the `outline_detection` parameter 
to `false` and selecting the tags that should be considered structure tags. This will split sentences 
using the `splitting_tags` parameter.

Sets whether the translation engine should respect the original formatting, even if it would usually 
correct some aspects.

When true, the response will include the billed_characters parameter, giving the 
number of characters from the request that will be counted by DeepL for billing purposes.

Language of the text to be translated. If this parameter is omitted, the API will attempt to 
detect the language of the text and translate it.

Sets whether the translation engine should first split the input into sentences. 

Possible values are:
  * 0 - no splitting at all, whole input is treated as one sentence
  * 1 (default when tag_handling is not set to html) - splits on punctuation and on newlines
  * nonewlines (default when tag_handling=html) - splits on punctuation only, ignoring newlines 

Sets which kind of tags should be handled. Options currently available:
 * `xml`
 * `html`

The language into which the text should be translated.

auth header

The translate function returns a JSON representation of the translations in the order the text parameters have been specified.

Bad request. Please check error message and your parameters.

Authorization failed. Please supply a valid `DeepL-Auth-Key` via the `Authorization` header.

The requested resource could not be found.

The request URL is too long. You can avoid this error by using a POST request instead of a GET request, and sending the parameters in the HTTP body.

Too many requests. Please wait and resend your request.

Quota exceeded. The character limit has been reached.

Resource currently unavailable. Try again later.

Request Translation

DeepL Documentation

Welcome to the developer home of DeepL API.

Introduction

About

Learn where to find your authentication key and how to access the DeepL API.

Access and authentication

A guide to creating API keys, getting API key-level usage, and setting API key-level limits.

Managing API keys

Make your first API requests to translate and improve text with the DeepL API.

Your first API request

Use our official Postman collection to get familiar with and test the DeepL API.

Test your API requests with Postman

The DeepL API supports the following languages. We will update this list as we introduce new languages.

Languages supported

Here's what we recommend reviewing to get your DeepL API application ready for production.

Pre-production checklist

Learn more about alpha and beta features in the DeepL API and how to best make use of them.

Alpha and beta features

Error handling

CORS requests

Translation context

Language detection

Subscription-level cost control

Learn how to translate XML content with the DeepL API.

XML handling

Learn how to work with structured XML content with the DeepL API.

Structured XML content

Learn how to customize XML outline detection with the DeepL API.

Customized XML outline detection

Learn how to translate HTML content with the DeepL API.

HTML handling

Brief summaries of recent DeepL API releases, such as support for new languages and document formats, new API parameters, and more.

Release notes

Here's what API users can expect when DeepL adds translation support for a new language or language variant.

API Reference

Translate text

Authorizations

Body

Response