Custom functions naming and localization

This article provides guidelines and best practices for naming custom functions and explains how to localize them.

Custom functions naming guidelines

A custom function is identified by an id and a name in the JSON metadata.

• id: Unique identifier used in code.
• name: Display name shown to users. It can be localized.

A function name can differ from the id for localization. If you don't need localization, it's best to use the same value for both.

A function's name and id share some similar rules.

• Both must start with a letter and be at least three characters.
• id: Only A–Z, 0–9, underscore, and period characters are allowed.
• name: Any Unicode alphabetic characters, underscore, and period characters are allowed.

Excel displays built-in function names in uppercase letters (for example, SUM). Use uppercase for your custom functions to help them blend in naturally.

Avoid names that match:

• A cell reference (A1 to XFD1048576 or R1C1 to R1048576C16384).
• An Excel 4.0 Macro Function (such as RUN, ECHO). For a full list of these functions, see this Excel Macro Functions Reference document.

Naming conflicts

If your function name conflicts with one from another add-in, Excel shows the #REF! error.

Fix conflicts by renaming your function or uninstalling the other add-in. For testing in multiple environments, use a short namespace prefix (such as ADDINNAME_FUNCTIONNAME).

Best practices

• Use extra function arguments instead of creating multiple similar function names. For example, GETNAME(firstName, middleName, lastName) is more efficient than having separate functions like GETFIRSTNAME, GETMIDDLENAME, and GETLASTNAME.
• Avoid abbreviations that aren’t clear. For example, INCREASETIME is easier to understand than INC.
• Choose action verbs for function names. Use GETZIPCODE instead of just ZIPCODE.
• Be consistent. Use the same verb for similar actions, such as DELETEZIPCODE and DELETEADDRESS.
• For streaming functions, add STREAM to the name or include a note in the description.
• Use a short vendor prefix in your function names to avoid conflicts with other add-ins. For example, use CONTOSO_GETPRICE or CONTOSO_TAX_CALC.

Naming constraints quick reference

Localize custom functions

You can localize both your add-in and your custom function names. Add localized function names in your JSON file and set locale overrides in the add-in only manifest.

Localize function names

To localize your custom functions, create a separate JSON metadata file for each language. In each file, add the name and description properties in the target language. Use functions.json for English and include the locale in the filename for other languages, such as functions-de.json for German.

Excel only localizes the name and description properties. The id is not localized and should remain unchanged after it's 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 you create a JSON for each language, add an override to your add-in only manifest that points to the correct file. The following manifest XML shows a default en-us locale plus an override JSON file URL for de-de (Germany).

<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 error handling best practices.

See also

• Manually create JSON metadata for custom functions
• Excel custom functions tutorial