{"id":2425,"date":"2026-11-12T07:01:21","date_gmt":"2026-11-11T23:01:21","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2425"},"modified":"2026-03-29T10:38:41","modified_gmt":"2026-03-29T10:38:41","slug":"how-to-use-rangesetphonetic-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-rangesetphonetic-in-the-xlwings-api-way\/","title":{"rendered":"How to use Range.SetPhonetic in the xlwings API way"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">In Excel, phonetic annotations are often used to display pronunciation guides, particularly for East Asian languages like Japanese and Chinese, where furigana or ruby characters are added above or alongside base text to indicate reading. The <code>Range.SetPhonetic<\/code> method in the Excel object model allows developers to programmatically set these phonetic text strings for a specified range. When working with Python and the xlwings library, which provides a clean API to interact with Excel, you can access this functionality to automate the addition or modification of phonetic information in your spreadsheets, enhancing data presentation for multilingual datasets.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The xlwings API mirrors the Excel object model closely, enabling direct calls to Excel methods via COM (on Windows) or Apple Script (on macOS). For the <code>SetPhonetic<\/code> method, the syntax in xlwings is straightforward. You start by referencing a <code>Range<\/code> object, typically through a workbook&#8217;s sheet, and then call the method with the phonetic text as an argument. The general syntax is: <code>range_object.api.SetPhonetic(Text)<\/code>. Here, <code>range_object<\/code> is an xlwings Range instance, such as <code>sheet.range('A1')<\/code>, and the <code>Text<\/code> parameter is a string representing the phonetic annotation you want to apply. This parameter is required and should match the base text&#8217;s pronunciation guide. Note that the method affects the entire range specified; if you apply it to a multi-cell range, the same phonetic text will be set for each cell, which may not be desired for varied content. Therefore, it&#8217;s common to use it on individual cells or iterate through a range to set distinct phonetic strings.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">To illustrate, consider a scenario where you have Japanese text in Excel and need to add furigana. In xlwings, you can write a script like:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>import xlwings as xw\n# Connect to an open workbook or start a new one\nwb = xw.Book('example.xlsx')\nsheet = wb.sheets&#91;'Sheet1']\n# Set phonetic text for cell A1\nsheet.range('A1').api.SetPhonetic('\u304b\u3093\u3058')\n# For multiple cells with different phonetic strings, loop through a range\ncells = sheet.range('A1:A3')\nphonetics = &#91;'\u3075\u308a\u304c\u306a1', '\u3075\u308a\u304c\u306a2', '\u3075\u308a\u304c\u306a3']\nfor i, cell in enumerate(cells):\n    cell.api.SetPhonetic(phonetics&#91;i])<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n","protected":false},"excerpt":{"rendered":"<p>In Excel, phonetic annotations are often used to display pronunciation guides, particularly for East&#8230;<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-2425","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2425","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=2425"}],"version-history":[{"count":2,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2425\/revisions"}],"predecessor-version":[{"id":3684,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2425\/revisions\/3684"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2425"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2425"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2425"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}