Getting started with pinyin helper

You can get an example document which contains some sample pinyin here, and which you can copy and use to become familiar with this add-on, as well as read more about how pinyin works. Alternatively create or use a document of your own containing some pinyin. 

Getting the add-on

Pinyin Helper is available from Google Document add-on menu, or directly from the Chrome store. 

Activating the add-on

Once installed, and  authorized

activate the add-on by selecting Interpret Tones from the menu. 

A sidebar will appear on the right of your document, and if you are at a point in your document where some pinyin with tone numbers is detected you'll see it being converted as below, (otherwise the text is copied over as is). Conversion is carried out in real time, as you type.

The panels

You'll see that the sidebar is split into a number of panels, each of which can be shown or hidden by clicking on the Show/Hide text on the blue panel separators..

The text shown in the panels is always a translation of the block of text at which the the document cursor is positioned, or of a selection of text.

Tone numbers to marks

The starting panel shown is the 'Tone number to mark' panel, which is the main function of this add-on.  The direction of conversion can be chosen by the 'Convert tones' radio button.

In this panel you'll see converted pinyin text - for example this;

Jin1tian1 tian1qi4 shi2fen1 nuan3huo, chu1men2 de shi2hou bu2bi4 chuan1 tai4 duo1 yi1fu.

will be converted into colorized and marked text, as in this example. 

Jīntiān tiān shífēn nuǎnhuo, chūmén de shíhou chuān tài duō fu.

To try , move the document cursor to some pinyin with tone numbers, or simply type some in. You'll notice that the contents of the panel will contain the the converted pinyin. If no pinyin with numbers is found, the current block of text is displayed as is. 

You can replace the pinyin in your document with the converted text shown in the panel with the replace button.

Tone marks to numbers

With the Convert tones to numbers option selected;

The conversion happens in the opposite direction. Your document selection of

diǎn de táng kàn lai hǎochī de hěn, ràng chī kǒu hǎobuhǎo?

will be shown on the sidebar as 

Ni3 dian3 de tang2cu4yu2 kan4 qi3lai hao3chi1 de hen3, rang4 wo3 chi1 yi4kou3 hao3buhao3?

To try out, move the document cursor to some pinyin with marks. You'll notice that the contents of the panel will contain the the converted pinyin. If no pinyin with marks is found the current block of text is displayed as is. You can replace the pinyin in your document with that shown in the panel by using the replace button.

HTML color markup

This panel shows the result of converting pinyin with tone numbers to marked up pinyin. In this case though, the result is a piece of html that you can copy into some other application. 

Many applications that use flash cards or similar media require this kind of code to display properly colored and marked up pinyin. You can use this panel as a feeder to these applications


There are a 3 options available on this panel
  • Convert tones. Select the direction of conversion as shown earlier
  • Colorize. By default, conversions from tone numbers to tone marks are colored according to the pinyin standard. This option turns off and on this colorization process.
  • Freeze panels. This stops conversion as you move through the document. If the panels are frozen, the Replace button is disabled to prevent accidental replacement of text not associated with what is being shown on the sidebar.

The current item

The helper operates on the whole element that the cursor is currently on (the whole paragraph, list item, table cell  and so on) by default. You can also convert a selected area simply by selecting the text in the document. For example, below I've selected an entire column of a table. The conversion is shown in the sidebar. The replace button will do all the selected elements at once.

Undo and Redo

You can use the regular Google Docs Redo/Undo buttons to cancel any replacements made by this.

You want to learn Google Apps Script?

Learning Apps Script, (and transitioning from VBA) are covered comprehensively in my my book, Going Gas - from VBA to Apps script, available All formats are available now from O'Reilly,Amazon and all good bookshops. You can also read a preview on O'Reilly

If you prefer Video style learning I also have two courses available. also published by O'Reilly.
Google Apps Script for Developers and Google Apps Script for Beginners.

You can get me on Google plus, Twitter or this forum.

For help and more information join our forumfollow the blogfollow me on twitter