Metadata API Developer Guide
jNewer Version Available
CustomLabels
This type extends the Metadata metadata type and inherits its fullName field. 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.
Declarative Metadata File Suffix and Directory Location
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.
Version
CustomLabels components are available in API version 14.0 and later.
Fields
| Field | Field Type | Description |
|---|---|---|
| fullName | string | 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. |
| labels | CustomLabel[] | A list of custom labels. |
CustomLabel
This metadata type represents a custom label. This type extends the Metadata metadata type and inherits its fullName field.
| Field | Field Type | Description |
|---|---|---|
| categories | string | 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. |
| fullName | string | 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. |
| language | string | Required. The language of the translated custom label. |
| protected | boolean | 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. |
| shortDescription | string | Required. An easily recognizable term to identify this custom label. This description is used in merge fields. |
| value | string | Required. The translated custom label. Maximum of 1000 characters. |
Usage
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.
Declarative Metadata Sample Definition
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>66.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>66.0</version>
10</Package>Wildcard Support in the Manifest File
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.