---
schema_version: "1"
id: 8a79af371de017612f82a8ef53d53e7f0234881eb20d1d15807fde5f6a0eebf0
title: CustomLabels
collection: legacydeveloper
version: current
locale: en-us
portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/meta_customlabels.md
canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_customlabels.htm
source_site: developer.salesforce.com
content_type: documentation
content_hash: a1730bd4ddded466e89f6122b7f84ec0ff6b28c51b3d82726c603581126447ba
description: The CustomLabels metadata type allows you to create custom labels that can be localized for use in different languages, countries, and currencies.
---
# CustomLabels

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

This type extends the [Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm "The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.") 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](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_translations.htm "Metadata type that enables work with translations for various supported languages. The ability to translate component labels is part of the Translation Workbench.") 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](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_translations.htm#translation_languages).

## Version

CustomLabels components are available in API version 14.0 and later.

## Fields

<table class="featureTable sort_table" summary="">



          <thead class="thead sorted" align="left">
            <tr>
              <th class="featureTableHeader  " id="d312843e122">Field</th>

              <th class="featureTableHeader  " id="d312843e125">Field Type</th>

              <th class="featureTableHeader  " id="d312843e128">Description</th>

            </tr>

          </thead>

          <tbody class="tbody">
            <tr>
              <td class="entry" headers="d312843e122" data-title="Field"><span class="keyword parmname">fullName</span></td>

              <td class="entry" headers="d312843e125" data-title="Field Type">string</td>

              <td class="entry" headers="d312843e128" data-title="Description">Required. The name of the custom label bundle. <p class="p">Inherited from
                  <a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm" title="The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.">Metadata</a>, this field is defined in the WSDL for this
                  metadata type. It must be specified when creating, updating, or
                  deleting. See <a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_createMetadata.htm" title="Adds one or more new metadata components to your organization synchronously."><samp class="codeph java">createMetadata()</samp></a> to see an example of
                  this field specified for a call.
                </p>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d312843e122" data-title="Field"><span class="keyword parmname">labels</span></td>

              <td class="entry" headers="d312843e125" data-title="Field Type">CustomLabel[]</td>

              <td class="entry" headers="d312843e128" data-title="Description">A list of custom labels.</td>

            </tr>

          </tbody>

        </table>

## CustomLabel

This metadata type represents a custom label. This type extends the [Metadata](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm "The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.") metadata type and inherits its fullName field.

<table class="featureTable sort_table" summary="">



          <thead class="thead sorted" align="left">
            <tr>
              <th class="featureTableHeader  " id="d312843e217">Field</th>

              <th class="featureTableHeader  " id="d312843e220">Field Type</th>

              <th class="featureTableHeader  " id="d312843e223">Description</th>

            </tr>

          </thead>

          <tbody class="tbody">
            <tr>
              <td class="entry" headers="d312843e217" data-title="Field"><span class="keyword parmname">categories</span></td>

              <td class="entry" headers="d312843e220" data-title="Field Type">string</td>

              <td class="entry" headers="d312843e223" data-title="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.</td>

            </tr>

            <tr>
              <td class="entry" headers="d312843e217" data-title="Field"><span class="keyword parmname">fullName</span></td>

              <td class="entry" headers="d312843e220" data-title="Field Type">string</td>

              <td class="entry" headers="d312843e223" data-title="Description">Required. The name of the custom label.<p class="p">Inherited from <a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/metadata.htm" title="The base class for all metadata types. You can’t edit this object. A component is an instance of a metadata type.">Metadata</a>,
                  this field is defined in the WSDL for this metadata type. It
                  must be specified when creating, updating, or deleting. See
                  <a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_createMetadata.htm" title="Adds one or more new metadata components to your organization synchronously."><samp class="codeph java">createMetadata()</samp></a> to
                  see an example of this field specified for a call.
                </p>
              </td>

            </tr>

            <tr>
              <td class="entry" headers="d312843e217" data-title="Field"><span class="keyword parmname">language</span></td>

              <td class="entry" headers="d312843e220" data-title="Field Type">string</td>

              <td class="entry" headers="d312843e223" data-title="Description">Required. The language of the translated custom label.</td>

            </tr>

            <tr>
              <td class="entry" headers="d312843e217" data-title="Field"><span class="keyword parmname">protected</span></td>

              <td class="entry" headers="d312843e220" data-title="Field Type">boolean</td>

              <td class="entry" headers="d312843e223" data-title="Description">Required. Indicates whether this component is protected (<samp class="codeph java">true</samp>) or not (<samp class="codeph java">false</samp>). Protected components can’t be
                linked to or referenced by components created in the installing
                organization.</td>

            </tr>

            <tr>
              <td class="entry" headers="d312843e217" data-title="Field"><span class="keyword parmname">shortDescription</span></td>

              <td class="entry" headers="d312843e220" data-title="Field Type">string</td>

              <td class="entry" headers="d312843e223" data-title="Description">Required. An easily recognizable term to identify this custom
                label. This description is used in merge fields.</td>

            </tr>

            <tr>
              <td class="entry" headers="d312843e217" data-title="Field"><span class="keyword parmname">value</span></td>

              <td class="entry" headers="d312843e220" data-title="Field Type">string</td>

              <td class="entry" headers="d312843e223" data-title="Description">Required. The translated custom label. Maximum of 1000
                characters.</td>

            </tr>

          </tbody>

        </table>

## 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.

<?xml version="1.0" encoding="UTF-8"?>
<CustomLabels xmlns="http://soap.sforce.com/2006/04/metadata">
    <labels\>
        <fullName\>quoteManual</fullName\>
        <value\>This is a manual quote.</value\>
        <language\>en\_US</language\>
        <protected\>false</protected\>
        <shortDescription\>Manual Quote</shortDescription\>
    </labels\>
    <labels\>
        <fullName\>quoteAuto</fullName\>
        <value\>This is an automatically generated quote.</value\>
        <language\>en\_US</language\>
        <protected\>false</protected\>
        <shortDescription\>Automatic Quote</shortDescription\>
    </labels\>
</CustomLabels\>

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

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName\>MyPkg</fullName\>
    <types\>
      <members\>\*</members\>
      <name\>CustomLabels</name\>
    </types\>
    <version\>68.0</version\>
</Package\>

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

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName\>MyPkg</fullName\>
    <types\>
      <members\>quoteManual</members\>
      <members\>quoteAuto</members\>
      <name\>CustomLabel</name\>
    </types\>
    <version\>68.0</version\>
</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](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm "The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders.").

## CustomLabels Limitation

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

#### See Also

- [Translations](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_translations.htm "Metadata type that enables work with translations for various supported languages. The ability to translate component labels is part of the Translation Workbench.")