ComboDocs

Translations

The translations utility functions provide a layer of abstraction for working with Polylang, a popular translation plugin for WordPress. These functions ensure compatibility even if Polylang isn't activated.

Available Functions

pl_e($string)

Displays a localized string with Polylang or the original string if Polylang isn't available.

Parameters:

  • $string: The string to translate.
1
// Display a translated string
2
pl_e('Welcome to our website');
3
4
// With HTML
5
pl_e('<a href="/contact">Contact us</a>');

pl__($string)

Returns a localized string with Polylang or the original string if Polylang isn't available.

Parameters:

  • $string: The string to translate.

Return Value:

Returns the translated string or the original string if Polylang isn't available.

1
// Get a translated string
2
$welcome = pl__('Welcome to our website');
3
echo $welcome;
4
5
// With variables
6
$username = 'John';
7
echo sprintf(pl__('Hello %s, welcome to our website'), $username);

Configuration

These functions use the global $cbo variable for configuration:

  • $cbo['pll']['reference']: Determines if strings are referenced by content ('string') or by key ('key').
  • $cbo['pll']['strings']: Associative array of strings to translate when reference is set to 'key'.
  • $cbo['pll']['domain']: Translation domain used by Polylang.

Modes of Operation

Content Mode (Default)

In this mode, strings are identified directly by their content:

1
// Configuration
2
$cbo['pll']['reference'] = 'string';
3
4
// Usage
5
pl_e('Welcome to our website'); // Displays "Welcome to our website" or its translation

Key Mode

In this mode, strings are identified by a key, allowing you to modify the source text without updating translations:

1
// Configuration
2
$cbo['pll']['reference'] = 'key';
3
$cbo['pll']['strings'] = [
4
  'welcome' => 'Welcome to our website',
5
  'thanks' => 'Thank you for your visit'
6
];
7
8
// Usage
9
pl_e('welcome'); // Displays "Welcome to our website" or its translation

Usage Examples

Multilingual Navigation

1
// Create a multilingual navigation menu
2
function multilingual_menu() {
3
  $menu_items = [
4
    ['url' => '/', 'text' => 'Home'],
5
    ['url' => '/about', 'text' => 'About Us'],
6
    ['url' => '/services', 'text' => 'Services'],
7
    ['url' => '/contact', 'text' => 'Contact']
8
  ];
9
  
10
  echo '<nav class="main-nav">';
11
  echo '<ul>';
12
  
13
  foreach ($menu_items as $item) {
14
    echo '<li>';
15
    echo '<a href="' . $item['url'] . '">' . pl__($item['text']) . '</a>';
16
    echo '</li>';
17
  }
18
  
19
  echo '</ul>';
20
  echo '</nav>';
21
}
22
23
// Usage
24
multilingual_menu();

Translatable Form Labels

1
// Create a contact form with translatable labels
2
function contact_form() {
3
  echo '<form class="contact-form" method="post">';
4
  
5
  echo '<div class="form-group">';
6
  echo '<label for="name">' . pl__('Name') . '</label>';
7
  echo '<input type="text" id="name" name="name" required>';
8
  echo '</div>';
9
  
10
  echo '<div class="form-group">';
11
  echo '<label for="email">' . pl__('Email') . '</label>';
12
  echo '<input type="email" id="email" name="email" required>';
13
  echo '</div>';
14
  
15
  echo '<div class="form-group">';
16
  echo '<label for="message">' . pl__('Message') . '</label>';
17
  echo '<textarea id="message" name="message" required></textarea>';
18
  echo '</div>';
19
  
20
  echo '<button type="submit">' . pl__('Send Message') . '</button>';
21
  echo '</form>';
22
}
23
24
// Usage
25
contact_form();

Best Practices

  • Use key mode for better maintainability when working with a team of translators.
  • Keep translations organized by using a consistent naming convention for keys.
  • Use sprintf for strings with variables to ensure proper translation.
  • Document your translation keys to help translators understand the context.
  • Use these functions consistently throughout your theme for better maintainability.
← Utilities OverviewVideos →