Skip to content

Latest commit

 

History

History
103 lines (84 loc) · 3.84 KB

custom-functions-localize.md

File metadata and controls

103 lines (84 loc) · 3.84 KB
ms.date description title ms.localizationpriority
11/06/2020
Localize your Excel custom functions.
Localize custom functions
medium

Localize custom functions

You can localize both your add-in and your custom function names. To do so, provide localized function names in the functions' JSON file and locale information in the XML manifest file.

Important

Autogenerated metadata doesn't work for localization so you need to update the JSON file manually. To learn how to do this, see Manually create JSON metadata for custom functions

[!includeExcel custom functions note]

Localize function names

To localize your custom functions, create a new JSON metadata file for each language. In each language JSON file, create name and description properties in the target language. The default file for English is named functions.json. Use the locale in the filename for each additional JSON file, such as functions-de.json to help identify them.

The name and description appear in Excel and are localized. However, the id of each function isn't localized. The id property is how Excel identifies your function as unique and shouldn't be changed once it is set.

The following JSON shows how to define a function with the id property "MULTIPLY." The name and description property of the function is localized for German. Each parameter name and description is also localized for German.

{
    "id": "MULTIPLY",
    "name": "SUMME",
    "description": "Summe zwei Zahlen",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "eins",
            "description": "Erste Nummer",
            "dimensionality": "scalar"
        },
        {
            "name": "zwei",
            "description": "Zweite Nummer",
            "dimensionality": "scalar"
        },
    ],
}

Compare the previous JSON with the following JSON for English.

{
    "id": "MULTIPLY",
    "name": "Multiply",
    "description": "Multiplies two numbers",
    "helpUrl": "http://www.contoso.com",
    "result": {
        "type": "number",
        "dimensionality": "scalar"
    },
    "parameters": [
        {
            "name": "one",
            "description": "first number",
            "dimensionality": "scalar"
        },
        {
            "name": "two",
            "description": "second number",
            "dimensionality": "scalar"
        },
    ],
}

Localize your add-in

After creating a JSON file for each language, update your XML manifest file with an override value for each locale that specifies the URL of each JSON metadata file. The following manifest XML shows a default en-us locale with an override JSON file URL for de-de (Germany). The functions-de.json file contains the localized German function names and ids.

<DefaultLocale>en-us</DefaultLocale>
...
<Resources>
     <bt:Urls>
        <bt:Url id="Contoso.Functions.Metadata.Url" DefaultValue="https://localhost:3000/dist/functions.json"/>
          <bt:Override Locale="de-de" Value="https://localhost:3000/dist/functions-de.json" />
        </bt:url>
        
     </bt:Urls>
</Resources>

For more information on the process of localizing an add-in, see Localization for Office Add-ins.

Next steps

Learn about naming conventions for custom functions or discover error handling best practices.

See also