{ "category": "Text functions", "display_name": "PHONETIC", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.PHONETIC", "implementation_state": { "answer_bank": null, "detail": "Recorded: 3 workbook cells.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": true, "state": "matches", "state_label": "Matches every recorded Excel answer", "summary": "Matches all 3 recorded answers", "workbook_corpus": { "cells": 3, "matched": 3 } }, "implementations": [ { "commit": "9e1884369a678158dd82d3d74188daf986995e87", "flavour": "excel-compatibility-candidate", "language": "Rust", "name": "CalcFunc", "own_code": [ "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L931-L931", "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L565-L575" ], "repository": "https://github.com/DnaCalc/DnaCalc", "shared_code": [ "catalogue/text_format::profile" ], "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/text_format.rs#L931-L931", "state": "matches", "suite": null, "summary": "Matches all 3 recorded answers" } ], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.PHONETIC.json", "name": "PHONETIC", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **`ASC` and `DBCS`** are the other locale-gated East-Asian text functions in Excel's surface,\n converting between half-width and full-width forms. Unlike `PHONETIC`, they are pure functions\n of their argument; they are gated by locale but not by stored metadata.\n- **`FINDB`, `LEFTB`, `LENB`, `MIDB`, `REPLACEB`, `RIGHTB`, `SEARCHB`** are the byte-variant text\n functions whose behaviour differs under DBCS locales — the other place in Excel where locale\n changes what a text function does. They are byte-counting variants, not metadata readers.\n- **No other function reads furigana.** There is no `ISPHONETIC`, no way to test whether a cell\n has an annotation other than calling `PHONETIC` and checking for an empty result, and no way to\n *write* furigana from a formula. The read is one-way and the surface is one function wide.\n- **`CELL`** is the nearest structural analogue in this Handbook: another function that returns\n stored workbook state rather than computing on a value.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n1. **This is not a text algorithm.** There is no rule that converts kanji to a reading — the\n mapping is ambiguous, which is exactly why the IME stores the reading rather than deriving it.\n Any implementation that tries to *generate* furigana is implementing a different function.\n2. **It requires a cell metadata channel.** An engine whose cell model is \"a value plus a format\"\n cannot hold furigana and therefore cannot implement `PHONETIC` at all. Declining is the correct\n response.\n3. **The multi-cell reduction is upper-left, silently.** Not an error, not an aggregate.\n4. **Non-contiguous is `#N/A`**, distinct from the reduction case, and the two must be told apart.\n5. **Any behavioural claim must carry a locale axis**, in the same way `INFO`'s claims must carry\n platform and build ([claim language and honesty](../model/06-claim-language.md)).\n\n\n", "quirks": "\n### Result and edge cases\n\n\nReturns `Text` — the stored furigana, which may be an empty string when the cell has none.\n\n- **No furigana means no result, not an error.** A cell of Latin text, a formula result, an\n imported value: none of these carries the annotation, and the expected answer is empty text.\n The Handbook has not confirmed this against a live build.\n- **Formula results carry no furigana.** `PHONETIC` on a cell containing `=A1&B1` reads the\n concatenation's stored annotation, and a concatenation does not produce one. This is the most\n common disappointment with the function: it works on typed data and not on derived data.\n- **The annotation can be edited independently of the text.** Excel's furigana editing UI lets a\n user change the reading without changing the kanji, which means `PHONETIC`'s answer is not\n derivable from the cell's value even in principle.\n- **Katakana versus hiragana.** Excel has a furigana *type* setting; which script the stored\n annotation uses is a property of how the cell was configured. What `PHONETIC` returns for each\n setting is not established here.\n- **Locale dependence is total.** Outside a Far East region setting, the documented requirement is\n not met and the function's behaviour is not something this page can state.\n\n\n\n### Errors\n\n\n- **`#N/A`** — documented, for a reference to non-adjacent cells (a multi-area reference).\n\nThe Handbook has read Microsoft's page and does not have a further documented error table to\nreproduce. In particular, what happens when the system region requirement is unmet — an error, an\nempty string, or a `#NAME?` because the function is not exposed — is **not established here**,\nand it is the first thing this page would probe.\n\n\n", "sources": "- Microsoft, \"PHONETIC function\" —\n .\n Read for this page: the description, the syntax, the `reference` argument description, the\n upper-left reduction for a range, the `#N/A` for non-adjacent cells, and the Far East region\n requirement.\n- Handbook, [the value universe](../model/01-value-universe.md) — the `Text` kind as UTF-16 code\n units, and the reference shapes this function distinguishes.\n- Handbook, [the execution context](../model/04-execution-context.md) — locale as an axis of the\n environment a function runs in.\n- Handbook, [claim language and honesty](../model/06-claim-language.md) — why a locale-scoped\n behaviour cannot be published without its axis.\n\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`PHONETIC(reference)` returns the **furigana** stored alongside the text in a cell.\n\nMicrosoft's description: \"Extracts the phonetic (furigana) characters from a text string.\"\n\n*The quoted one-line description is Microsoft's text, from its support article .*\n\nUnderstanding this function requires one fact about Japanese text in Excel that has no analogue\nin the rest of the worksheet surface: **a cell can carry a second string that is not its value.**\nWhen Japanese text is typed through an IME, the IME knows the reading that produced the kanji,\nand Excel stores that reading as *furigana* — a phonetic annotation attached to the cell. It is\nnot part of the cell's text value, it is not visible unless furigana display is switched on, and\nno other function can see it.\n\n`PHONETIC` is the only worksheet function that reads it.\n\nThis makes `PHONETIC` structurally unlike every other text function. `LEFT`, `UPPER`, `LEN` and\nthe rest are pure functions of a string: given the same input they compute the same output\nanywhere, on any machine, in any locale. `PHONETIC` is not a computation on its argument at all —\nit is a **retrieval of stored metadata**, and the metadata was created by the input method at the\ntime the text was typed. Two cells displaying identical kanji can return different furigana, or\none can return furigana and the other nothing, depending entirely on how each was entered. Text\nproduced by a formula, imported from a file, or pasted as values generally carries no furigana at\nall.\n\nThree further constraints, all documented:\n\n1. **The system region must be set to a Far East language** — Japanese, Chinese or Korean — for\n the function to work.\n2. **A multi-cell reference is reduced to its upper-left cell**; the function does not aggregate.\n3. **A non-contiguous reference is an error**, not a reduction.\n\n\n\n### Arguments\n\n\n`reference` — required, exactly one. Microsoft's description: \"Text string or a reference to a\nsingle cell or a range of cells that contain a furigana text string.\"\n\nThe name `reference` is doing real work here. Furigana is a property of a *cell*, so the useful\nform of the call is a reference; a literal text string has no furigana attached to it, because\nthere was never an IME session that produced it. The documentation admits a text string as an\nargument form, but what a text literal could usefully return is not something this Handbook can\nstate.\n\nThe multi-cell form is admitted and reduced: with a range, the answer comes from the upper-left\ncell only. This is the same reduction `CELL(\"contents\", …)` performs, and it is worth knowing\nbecause it is silent — a range argument does not error, it just quietly ignores everything but\none cell.\n\n\n" }, "signature": { "display": "PHONETIC(reference)", "parameters": [ { "description": null, "name": "reference", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "implemented", "reason": null }, "arity": { "max": 1, "min": 1 }, "category": "Text functions", "classification": {}, "descriptions": { "long": null, "short": "The phonetic (furigana) reading stored with Japanese text", "short_source": "dna-calc-own" }, "docs": { "english_description": "Extracts the phonetic (furigana) characters from a text string", "microsoft_url": "https://support.microsoft.com/en-us/office/phonetic-function-9a329dac-0c0f-42f8-9a55-639086988554" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "PHONETIC" }, { "locale": "bg-BG", "name": "PHONETIC" }, { "locale": "cs-CZ", "name": "ZVUKOVÉ" }, { "locale": "da-DK", "name": "FONETISK" }, { "locale": "de-DE", "name": "PHONETIC" }, { "locale": "el-GR", "name": "PHONETIC" }, { "locale": "en-AU", "name": "PHONETIC" }, { "locale": "en-GB", "name": "PHONETIC" }, { "locale": "en-US", "name": "PHONETIC" }, { "locale": "es-ES", "name": "FONETICO" }, { "locale": "et-EE", "name": "PHONETIC" }, { "locale": "fi-FI", "name": "FONEETTINEN" }, { "locale": "fr-FR", "name": "PHONÉTIQUE*" }, { "locale": "he-IL", "name": "PHONETIC" }, { "locale": "hr-HR", "name": "PHONETIC" }, { "locale": "hu-HU", "name": "FONETIKUS" }, { "locale": "id-ID", "name": "PHONETIC" }, { "locale": "it-IT", "name": "PHONETIC" }, { "locale": "ja-JP", "name": "PHONETIC" }, { "locale": "ko-KR", "name": "PHONETIC" }, { "locale": "lt-LT", "name": "PHONETIC" }, { "locale": "lv-LV", "name": "PHONETIC" }, { "locale": "nb-NO", "name": "FONETISK" }, { "locale": "nl-NL", "name": "FONETISCH" }, { "locale": "pl-PL", "name": "PHONETIC" }, { "locale": "pt-BR", "name": "PHONETIC" }, { "locale": "pt-PT", "name": "FONÉTICA" }, { "locale": "ro-RO", "name": "PHONETIC" }, { "locale": "ru-RU", "name": "PHONETIC" }, { "locale": "sk-SK", "name": "PHONETIC" }, { "locale": "sl-SI", "name": "PHONETIC" }, { "locale": "sr-Latn-RS", "name": "PHONETIC" }, { "locale": "sv-SE", "name": "PHONETIC" }, { "locale": "th-TH", "name": "PHONETIC" }, { "locale": "tr-TR", "name": "SES işlevi" }, { "locale": "uk-UA", "name": "PHONETIC" }, { "locale": "vi-VN", "name": "PHONETIC" }, { "locale": "zh-CN", "name": "PHONETIC" }, { "locale": "zh-HK", "name": "PHONETIC" }, { "locale": "zh-TW", "name": "PHONETIC" } ], "signature": { "display": "PHONETIC(reference)", "parameters": [ { "description": null, "name": "reference", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "PHONETIC", "version_marker": null, "xlcall": { "code": "360", "symbol": "xlfPhonetic" } }, "microsoft": "https://support.microsoft.com/en-us/office/phonetic-function-9a329dac-0c0f-42f8-9a55-639086988554" }, "try_it": { "formula": "=PHONETIC(B2)", "inputs": { "B2": 1 }, "note": "Input cells in this preview do not carry phonetic annotations. OneCalc therefore returns #N/A for this example.", "preview_status": "worksheet-error" }, "url": "https://handbook.dnacalc.com/functions/PHONETIC.html", "variants": [], "versions": [] }