Hide
Apps Script

Quickstart: Add-on for Google Docs

Complete the steps described in the rest of this page, and in about five minutes you'll have created a Google Docs add-on that translates text in a sidebar. To see what the add-on looks like when it's finished, just install Translate from the Google Docs add-ons store.

Set it up

  1. Create a new Google Doc.
  2. From within your new document, select the menu item Tools > Script editor. If you are presented with a welcome screen, click Blank Project.
  3. Delete any code in the script editor and paste in the code below. Open code in new window
    /**
     * Creates a menu entry in the Google Docs UI when the document is opened.
     *
     * @param {object} e The event parameter for a simple onOpen trigger. To
     *     determine which authorization mode (ScriptApp.AuthMode) the trigger is
     *     running in, inspect e.authMode.
     */
    function onOpen(e) {
      DocumentApp.getUi().createAddonMenu()
          .addItem('Start', 'showSidebar')
          .addToUi();
    }
    
    /**
     * Runs when the add-on is installed.
     *
     * @param {object} e The event parameter for a simple onInstall trigger. To
     *     determine which authorization mode (ScriptApp.AuthMode) the trigger is
     *     running in, inspect e.authMode. (In practice, onInstall triggers always
     *     run in AuthMode.FULL, but onOpen triggers may be AuthMode.LIMITED or
     *     AuthMode.NONE.)
     */
    function onInstall(e) {
      onOpen(e);
    }
    
    /**
     * Opens a sidebar in the document containing the add-on's user interface.
     */
    function showSidebar() {
      var ui = HtmlService.createHtmlOutputFromFile('Sidebar')
          .setTitle('Translate');
      DocumentApp.getUi().showSidebar(ui);
    }
    
    /**
     * Gets the text the user has selected. If there is no selection,
     * this function displays an error message.
     *
     * @return {Array.<string>} The selected text.
     */
    function getSelectedText() {
      var selection = DocumentApp.getActiveDocument().getSelection();
      if (selection) {
        var text = [];
        var elements = selection.getSelectedElements();
        for (var i = 0; i < elements.length; i++) {
          if (elements[i].isPartial()) {
            var element = elements[i].getElement().asText();
            var startIndex = elements[i].getStartOffset();
            var endIndex = elements[i].getEndOffsetInclusive();
    
            text.push(element.getText().substring(startIndex, endIndex + 1));
          } else {
            var element = elements[i].getElement();
            // Only translate elements that can be edited as text; skip images and
            // other non-text elements.
            if (element.editAsText) {
              var elementText = element.asText().getText();
              // This check is necessary to exclude images, which return a blank
              // text element.
              if (elementText != '') {
                text.push(elementText);
              }
            }
          }
        }
        if (text.length == 0) {
          throw 'Please select some text.';
        }
        return text;
      } else {
        throw 'Please select some text.';
      }
    }
    
    /**
     * Gets the stored user preferences for the origin and destination languages,
     * if they exist.
     *
     * @return {Object} The user's origin and destination language preferences, if
     *     they exist.
     */
    function getPreferences() {
      var userProperties = PropertiesService.getUserProperties();
      var languagePrefs = {
        originLang: userProperties.getProperty('originLang'),
        destLang: userProperties.getProperty('destLang')
      };
      return languagePrefs;
    }
    
    /**
     * Gets the user-selected text and translates it from the origin language to the
     * destination language. The languages are notated by their two-letter short
     * form. For example, English is 'en', and Spanish is 'es'. The origin language
     * may be specified as an empty string to indicate that Google Translate should
     * auto-detect the language.
     *
     * @param {string} origin The two-letter short form for the origin language.
     * @param {string} dest The two-letter short form for the destination language.
     * @param {boolean} savePrefs Whether to save the origin and destination
     *     language preferences.
     * @return {string} The result of the translation.
     */
    function runTranslation(origin, dest, savePrefs) {
      var text = getSelectedText();
      if (savePrefs == true) {
        var userProperties = PropertiesService.getUserProperties();
        userProperties.setProperty('originLang', origin);
        userProperties.setProperty('destLang', dest);
      }
    
      var translated = [];
      for (var i = 0; i < text.length; i++) {
        translated.push(LanguageApp.translate(text[i], origin, dest));
      }
    
      return translated.join('\n');
    }
    
    /**
     * Replaces the text of the current selection with the provided text, or
     * inserts text at the current cursor location. (There will always be either
     * a selection or a cursor.) If multiple elements are selected, only inserts the
     * translated text in the first element that can contain text and removes the
     * other elements.
     *
     * @param {string} newText The text with which to replace the current selection.
     */
    function insertText(newText) {
      var selection = DocumentApp.getActiveDocument().getSelection();
      if (selection) {
        var replaced = false;
        var elements = selection.getSelectedElements();
        if (elements.length == 1 &&
            elements[0].getElement().getType() ==
            DocumentApp.ElementType.INLINE_IMAGE) {
          throw "Can't insert text into an image.";
        }
        for (var i = 0; i < elements.length; i++) {
          if (elements[i].isPartial()) {
            var element = elements[i].getElement().asText();
            var startIndex = elements[i].getStartOffset();
            var endIndex = elements[i].getEndOffsetInclusive();
    
            var remainingText = element.getText().substring(endIndex + 1);
            element.deleteText(startIndex, endIndex);
            if (!replaced) {
              element.insertText(startIndex, newText);
              replaced = true;
            } else {
              // This block handles a selection that ends with a partial element. We
              // want to copy this partial text to the previous element so we don't
              // have a line-break before the last partial.
              var parent = element.getParent();
              parent.getPreviousSibling().asText().appendText(remainingText);
              // We cannot remove the last paragraph of a doc. If this is the case,
              // just remove the text within the last paragraph instead.
              if (parent.getNextSibling()) {
                parent.removeFromParent();
              } else {
                element.removeFromParent();
              }
            }
          } else {
            var element = elements[i].getElement();
            if (!replaced && element.editAsText) {
              // Only translate elements that can be edited as text, removing other
              // elements.
              element.clear();
              element.asText().setText(newText);
              replaced = true;
            } else {
              // We cannot remove the last paragraph of a doc. If this is the case,
              // just clear the element.
              if (element.getNextSibling()) {
                element.removeFromParent();
              } else {
                element.clear();
              }
            }
          }
        }
      } else {
        var cursor = DocumentApp.getActiveDocument().getCursor();
        var surroundingText = cursor.getSurroundingText().getText();
        var surroundingTextOffset = cursor.getSurroundingTextOffset();
    
        // If the cursor follows or preceds a non-space character, insert a space
        // between the character and the translation. Otherwise, just insert the
        // translation.
        if (surroundingTextOffset > 0) {
          if (surroundingText.charAt(surroundingTextOffset - 1) != ' ') {
            newText = ' ' + newText;
          }
        }
        if (surroundingTextOffset < surroundingText.length) {
          if (surroundingText.charAt(surroundingTextOffset) != ' ') {
            newText += ' ';
          }
        }
        cursor.insertText(newText);
      }
    }
    
    
  4. Create a new file by selecting the menu item File > New > Html file. Name the file "Sidebar".
  5. Delete any code in the new editor tab and paste in the code below. Open code in new window
    <link rel="stylesheet" href="https://ssl.gstatic.com/docs/script/css/add-ons.css">
    <!-- The CSS package above applies Google styling to buttons and other elements. -->
    
    <style>
    .branding-below {
      bottom: 56px;
      top: 0;
    }
    
    .branding-text {
      left: 7px;
      position: relative;
      top: 3px;
    }
    
    .col-contain {
      overflow: hidden;
    }
    
    .col-one {
      float: left;
      width: 50%;
    }
    
    .logo {
      vertical-align: middle;
    }
    
    .radio-spacer {
      height: 20px;
    }
    
    .width-100 {
      width: 100%;
    }
    </style>
    
    <div class="sidebar branding-below">
      <form>
        <div class="block col-contain">
          <div class="col-one">
            <b>Selected text</b>
            <div>
              <input type="radio" name="origin" id="radio-origin-auto" value="" checked="checked">
              <label for="radio-origin-auto">Auto-detect</label>
            </div>
            <div>
              <input type="radio" name="origin" id="radio-origin-en" value="en">
              <label for="radio-origin-en">English</label>
            </div>
            <div>
              <input type="radio" name="origin" id="radio-origin-fr" value="fr">
              <label for="radio-origin-fr">French</label>
            </div>
            <div>
              <input type="radio" name="origin" id="radio-origin-de" value="de">
              <label for="radio-origin-de">German</label>
            </div>
            <div>
              <input type="radio" name="origin" id="radio-origin-ja" value="ja">
              <label for="radio-origin-ja">Japanese</label>
            </div>
            <div>
              <input type="radio" name="origin" id="radio-origin-es" value="es">
              <label for="radio-origin-es">Spanish</label>
            </div>
          </div>
          <div>
            <b>Translate into</b>
            <div class="radio-spacer">
            </div>
            <div>
              <input type="radio" name="dest" id="radio-dest-en" value="en">
              <label for="radio-dest-en">English</label>
            </div>
            <div>
              <input type="radio" name="dest" id="radio-dest-fr" value="fr">
              <label for="radio-dest-fr">French</label>
            </div>
            <div>
              <input type="radio" name="dest" id="radio-dest-de" value="de">
              <label for="radio-dest-de">German</label>
            </div>
            <div>
              <input type="radio" name="dest" id="radio-dest-ja" value="ja" checked="checked">
              <label for="radio-dest-ja">Japanese</label>
            </div>
            <div>
              <input type="radio" name="dest" id="radio-dest-es" value="es">
              <label for="radio-dest-es">Spanish</label>
            </div>
          </div>
        </div>
    
        <div class="block form-group">
          <label for="translated-text"><b>Translation</b></label>
          <textarea class="width-100" id="translated-text" rows="10"></textarea>
        </div>
    
        <div class="block">
          <input type="checkbox" id="save-prefs">
          <label for="save-prefs">Use these languages by default</label>
        </div>
    
       <div class="block" id="button-bar">
          <button class="blue" id="run-translation">Translate</button>
          <button id="insert-text">Insert</button>
        </div>
      </form>
    </div>
    
    <div class="sidebar bottom">
      <img alt="Add-on logo" class="logo" width="27" height="27"
          src="https://googledrive.com/host/0B0G1UdyJGrY6XzdjQWF4a1JYY1k/translate-logo-small.png">
      <span class="gray branding-text">Translate sample by Google</span>
    </div>
    
    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js">
    </script>
    <script>
      /**
       * On document load, assign click handlers to each button and try to load the
       * user's origin and destination language preferences if previously set.
       */
      $(function() {
        $('#run-translation').click(runTranslation);
        $('#insert-text').click(insertText);
        google.script.run.withSuccessHandler(loadPreferences)
            .withFailureHandler(showError).getPreferences();
      });
    
      /**
       * Callback function that populates the origin and destination selection
       * boxes with user preferences from the server.
       *
       * @param {Object} languagePrefs The saved origin and destination languages.
       */
      function loadPreferences(languagePrefs) {
        $('input:radio[name="origin"]')
            .filter('[value=' + languagePrefs.originLang + ']')
            .attr('checked', true);
        $('input:radio[name="dest"]')
            .filter('[value=' + languagePrefs.destLang + ']')
            .attr('checked', true);
      }
    
      /**
       * Runs a server-side function to translate the user-selected text and update
       * the sidebar UI with the resulting translation.
       */
      function runTranslation() {
        this.disabled = true;
        $('#error').remove();
        var origin = $('input[name=origin]:checked').val();
        var dest = $('input[name=dest]:checked').val();
        var savePrefs = $('#save-prefs').is(':checked');
        google.script.run
            .withSuccessHandler(
              function(translatedText, element) {
                $('#translated-text').val(translatedText);
                element.disabled = false;
              })
            .withFailureHandler(
              function(msg, element) {
                showError(msg, $('#button-bar'));
                element.disabled = false;
              })
            .withUserObject(this)
            .runTranslation(origin, dest, savePrefs);
      }
    
      /**
       * Runs a server-side function to insert the translated text into the document
       * at the user's cursor or selection.
       */
      function insertText() {
        this.disabled = true;
        $('#error').remove();
        google.script.run
            .withSuccessHandler(
              function(returnSuccess, element) {
                element.disabled = false;
              })
            .withFailureHandler(
              function(msg, element) {
                showError(msg, $('#button-bar'));
                element.disabled = false;
              })
            .withUserObject(this)
            .insertText($('#translated-text').val());
      }
    
      /**
       * Inserts a div that contains an error message after a given element.
       *
       * @param msg The error message to display.
       * @param element The element after which to display the error.
       */
      function showError(msg, element) {
        var div = $('<div id="error" class="error">' + msg + '</div>');
        $(element).after(div);
      }
    </script>
    
    
  6. Select the menu item File > Save all. Name your new script "Translate Quickstart" and click OK (The script's name is shown to end users in several places, including the authorization dialog.)

Try it out

  1. Switch back to your document and reload the page.
  2. After a few seconds, a Translate Quickstart sub-menu will appear under the Add-ons menu. (If you chose a different name for your script, that name will appear instead.) Click Add-ons > Translate Quickstart > Start.
  3. A dialog box will appear and tell you that the script requires authorization. Click Continue. A second dialog box will then request authorization for specific Google services. Read the notice carefully, then click Accept.
  4. A sidebar will appear. To test it, type some text into your document, then select it and click the blue Translate button. To replace the text in the document, click Insert.

Publish

Since this is an example add-on, our tutorial ends here. If you were developing a real add-on, the last step would be to publish it for other people to find and install. To learn more, check out our add-ons guide.

Learn more

To continue learning about how to extend Google Docs with Apps Script, take a look at the following resources: