CustomLabels

The CustomLabels metadata type allows you to create custom labels that can be localized for use in different languages, countries, and currencies.

Custom labels are custom text values, up to 1,000 characters in length that can be accessed from Apex classes or Visualforce pages. For more information, see “Custom Labels” in Salesforce Help.

This type extends Metadata and inherits its fields.

Master custom label values are stored in the CustomLabels.labels file. Translations for custom labels can be retrieved through Translations in Metadata API. Translations are stored in files under the translations folder with the name format of localeCode.translation, where localeCode is the locale code of the translation language. The supported locale codes are listed in Language.

Introduced in API version 14.0.

• Type: string

• Required: No

• Description: Required. The name of the custom label bundle.

  Inherited from Metadata, this field is defined in the WSDL for this metadata type. It must be specified when creating, updating, or deleting. See createMetadata() to see an example of this field specified for a call.

• Type: CustomLabel[]
• Required: No
• Description: A list of custom labels.

This metadata type represents a custom label.

This type extends Metadata and inherits its fields.

• Type: string
• Required: No
• Description: A comma-separated list of categories for the label. This field can be used in filter criteria when creating custom label list views. Maximum of 255 characters.

• Type: string

• Required: No

• Description: Required. The name of the custom label.

  Inherited from Metadata, this field is defined in the WSDL for this metadata type. It must be specified when creating, updating, or deleting. See createMetadata() to see an example of this field specified for a call.

• Type: string
• Required: Yes
• Description: Required. The language of the translated custom label.

• Type: boolean
• Required: Yes
• Description: Required. Indicates whether this component is protected (true) or not (false). Protected components can’t be linked to or referenced by components created in the installing organization.

• Type: string
• Required: Yes
• Description: Required. An easily recognizable term to identify this custom label. This description is used in merge fields.

• Type: string
• Required: Yes
• Description: Required. The translated custom label. Maximum of 1000 characters.

This is a sample XML definition of a custom label component.

1<?xml version="1.0" encoding="UTF-8"?>
2<CustomLabels xmlns="http://soap.sforce.com/2006/04/metadata">
3    <labels>
4        <fullName>quoteManual</fullName>
5        <value>This is a manual quote.</value>
6        <language>en_US</language>
7        <protected>false</protected>
8        <shortDescription>Manual Quote</shortDescription>
9    </labels>
10    <labels>
11        <fullName>quoteAuto</fullName>
12        <value>This is an automatically generated quote.</value>
13        <language>en_US</language>
14        <protected>false</protected>
15        <shortDescription>Automatic Quote</shortDescription>
16    </labels>
17</CustomLabels>

This is a sample manifest file for retrieving all custom labels in the organization by using the CustomLabels type.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <fullName>MyPkg</fullName>
4    <types>
5      <members>*</members>
6      <name>CustomLabels</name>
7    </types>
8    <version>68.0</version>
9</Package>

This is a sample manifest file for retrieving two custom labels by name. Notice it uses the CustomLabel singular type.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <fullName>MyPkg</fullName>
4    <types>
5      <members>quoteManual</members>
6      <members>quoteAuto</members>
7      <name>CustomLabel</name>
8    </types>
9    <version>68.0</version>
10</Package>

Use CustomLabels with the wildcard character (*) for members in the package.xml manifest file to retrieve all custom labels that are defined in your organization. CustomLabels doesn’t support retrieving one or more custom labels by name. To retrieve specific labels by name, use CustomLabel and specify the label names as members.

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.

Before you use the CustomLabels metadata type, understand the limitations of this feature. You can’t retrieve the CustomLabels metadata type with a namespace.