Expand the reach of your apps by building them for a worldwide audience. Learn how to create localized tvOS apps that perform seamlessly regardless of country and language. Gain insights into such topics as handling server-side content, matching preferred languages, and localizing images and text direction.
Hello, and welcome to
Localization Best Practices on
My name is Joaquim Lobo Silva,
and over the next few minutes,
I'm going to walk you through
some of the steps you'll want to
take to build a great localized
application experience on tvOS.
Apple TV is available in
multiple languages and regions.
And new in tvOS 11, is the
addition of Arabic and Hebrew
and selectable system languages.
Adding international support to
your app, is an incredible
opportunity to reach new markets
and enable more users to use and
enjoy your content.
And we have a wide variety of
APIs and tools to help you do
Let's dive right in.
I'm going to divide this topic
into three different sections.
First, I'll talk about best
practices on how to handle text
that is displayed to your user.
Then, I'll cover some
considerations regarding layout
And finally, the steps needed to
export your localizable content,
as well as test your app, to
make sure it all works.
So, let's get started with text.
Any text that will be presented
to your user, should be
displayed in their preferred
If you have text in Storyboard
elements, there's nothing else
you need to do.
These are marked "localizable"
If you have strings and code
that you're planning on
presenting, these should be
wrapped with a call to
This will essentially mark your
string as "localizable," so that
it is included in the file that
you will send out for
In both of these cases, comments
on the strings themselves, are
extremely useful, and should be
included as part of every
localizable string in your app.
Comments can be the defining
factor between great translated
content and text that feels
unnatural or unclear.
Here's an example of a localized
string in code.
As you can see, this is simply
the English word "subscribe"
with a comment describing where
it will appear in my UI, as well
as what it does within the
context of my app.
Comments are just as easy to add
to Storyboard elements as well.
For every element, you can
simply add a comment in the
Comment for Localizer text
field, in the Identity
Do note that when it comes to
displaying text in your app,
localized strings are not the
only way to accomplish this.
In fact, it's very likely that
you have a number of use cases
that are covered by our
These help you format and
display things like numbers,
currencies, dates, units such as
length and mass, and much more,
without having to write out
localized strings for these.
Here's an example of date
I simply create the object, and
in this case, I only care about
showing time, so I set the Time
Style to a length value of my
preference, and finally get a
formatted string out of the
This string is guaranteed to not
only be in the user's preferred
language, but it also takes care
of a number of other formatting
contexts, such as whether the
user prefers 12 or 24-hour time.
For much more information on how
to make the most out of
formatters, as well as some
guidance on their international
prowess, I highly recommend you
check out these two talks from
Let's talk about remote content.
Any text that you're fetching
from a server, should also match
your app's running language.
I'm referring to, for example,
media content and descriptions
that are shown in your app.
For this to happen, you'll need
to inform your server what
language the content should
actually be in.
We have APIs that let you know
what language you're app is
currently running in, and these
do a lot of the heavy lifting in
terms of choosing the best
language out of the ones that
you support, while respecting
the user's preferences.
Things like regional variance
and any appropriate regional
fallbacks, are also considered.
Just to give a few small
examples, I have here a table
where the first column shows a
language that the user might
have picked for their system
The second column shows
potential languages that your
application supports, and the
third column would be the end
result, given the circumstances.
For the first example, the user
has picked Spanish as their
language, with their region set
to Mexico, hence the "es-MX"
The app supports both Spanish
for Spain, as well as Latin
American Spanish and the list of
localizations, that's "es-EX"
and "es-419" respectively.
And the runtime will go ahead
and pick the Latin American
Spanish variant for your app.
Similarly, for the second
example, the user has picked
Chinese with the region set to
China, and Bundle will go ahead
and pick "Simplified Chinese"
out of the languages that your
To get the language that your
app is running in, all you have
to do is get the first object of
preferred localizations from
your app's bundle.
This will return a language
identifier that you can send to
Alternatively, if your server
supports a different set of
languages relative to your app,
you can also get the best
possible language match out of
those, using Bundle's Preferred
Localizations from Available.
So, that's an overview of how to
handle text in your app.
Text can be marked as
localizable through using
Storyboards, as well as calling
NSLocalizedString and code.
We have a number of formatters
that help display and
contextualize information, like
dates and numbers.
For remote content, you can rely
on the Bundle API to help inform
your server what language your
content should be displayed in.
With that, let's talk a little
about layout and images.
When it comes to layout, there
are typically two different
aspects to adapt for.
The first one is potential
differences in word length.
For example, here's the word
"backup" in English, and here's
that same word in Finnish.
Translations being significantly
longer or shorter, can impact
the way your layout behaves at
runtime, and you should design
for this accordingly.
The other aspect is script
English uses the Latin alphabet,
which is read and parsed from
left to right.
Some languages like Arabic, have
their scripts read from right to
As a result, there are a number
of design considerations
regarding flow and ordering of
For example, in a right to left
language, the first item in a
list is expected to be in the
far right, as opposed to the far
If your app uses UIKit to
display user interface elements,
there are a few technologies
that you can use to easily adapt
for these two different aspects.
It's highly recommended that you
start off with exploring
UIStackView is a streamlined
interface for laying out a
series of views, either
horizontally or vertically.
And these can be nested to
create complex layouts as shown
In this example, you can see
that I have some numbered views,
and the general flow of
information here is left to
right, as expected for a
language like English.
The thing about UIStackView is
that under the hood, it relies
on something called Auto Layout.
Auto Layout is a set of APIs
that help determine layout
relationships between views,
such that if the size of a view
changes, other views can adapt
accordingly to prevent overlap
In addition to this, Auto Layout
also relies on the concept of
leading and trailing
These are essentially left and
right position constraints, but
that evaluate to right and left
when running in a right to left
So, for the stack views above,
the layout would automatically
change to right to left, when
running in, for example, Arabic
And this can be accomplished
without having to write a single
line of extra code for different
For apps using TVMLKit, the
standard templates provided do
all the heavy lifting for the
two aspects I mentioned.
In particular for right to left
languages, once again, with the
addition of Arabic and Hebrew
and selectable system languages,
we have some new APIs that
leverage the same concept of
leading and trailing for TVMLKit
elements that have a specific
position or alignment.
Similarly, for margins and
padding, we have new media
queries to help specify custom
values for a specific layout
To explore these new features in
depth, please be sure to check
out Advances in TVMLKit.
Let's move on to images.
And for this, I'm going to
briefly cover an approach to
keep in mind for different
Typically, images in your app
will fall into one of three
The first one, likely to be most
of your images, is universal.
These are images that do not
need specific adaptation for a
The second category, is images
that do have some direction
associated to them.
This can be a number of things
such as navigation arrows,
disclosure indicators, or in
this case, a simplified
representation of text.
The only step required for these
images to adapt for the opposite
layout direction, is to
graphically mirror them.
And now, we have the correct
Lastly, the third category is
similar to the second, but these
are relatively complex such that
simply flipping them would
actually produce an incorrect
In this example, I've a bulleted
list with checkmarks, but
checkmarks as a symbol should
not be mirrored.
So, in this case, what I really
need is two separate images, one
for each layout direction.
Xcode makes it very easy to
handle all of these cases, right
from within your Asset Catalog.
For each asset, you can specify
whether or not an image has a
fixed direction or if it should
adapt either through mirroring
or through specifying different
Then, it's simply a matter of
using images regularly either in
code or in Interface Builder, as
For much more information on how
to use asset catalogs for
different layout directions,
please check out this talk from
So, that's layout and images.
We've seen how both UIKit and
TVMLKit have very high-level
approaches for adaptive layouts,
as well as some of the new APIs
introduced in tvOS 11 for right
to left support.
And also, the concept of image
directionality and how this is
part of image assets.
Last but not least, let's cover
how you can actually add a
language to your app, from start
Adding a language to your
project is done in the Project
Select your project file from
within Xcode, and in the Project
Settings, you can add supported
languages in the Localization
Xcode will manage and keep track
of any applicable file
management, such as extracting
text from Storyboards, as well
as strings you've marked as
localizable in code.
When you're ready to send your
app's content out for
translation, this is as simple
as selecting your project file
in Xcode, and choosing Export
for Localization in the Editor
Xcode will generate a
translation interchange file, or
XLIFF, for you to send out for
Once you have this file back,
reimporting this content into
your Xcode project is just a
matter of selecting Import
Localizations from that same
Xcode will update all of the
relevant files and resources to
make sure that when your app is
built, all up to date supported
translations are included.
Once this is done, it's a good
idea to test your app in the
different environments that
you're planning on supporting.
Xcode provides a number of
different features to help you
do this, and you can get a good
idea of how your app behaves in
these circumstances, even if you
don't speak the languages you
For Objective-C code, the Static
Analyzer supports making sure
that any string you provide to a
UI element is appropriately
marked as "localizable."
Not only that, you can also
check if any of your localized
strings are missing comments.
For running your app in
different languages, there's a
convenient set of options for
simulating a specific language
or region setting.
In addition to this, Xcode also
lets you run your app in a
simulated environment, or pseudo
language, such as right to left,
so that you can continue testing
your app in your base language,
but also see how it would look
like in a right to left
This can be done in the Options
tab of the Scheme Editor for
The Localizing with Xcode 9
session, covers all of these
features and much more for
getting the most out of the tool
set when preparing your app for
And that's an overview of
localizing and testing your
application, from within Xcode.
We've seen how you can add
supported languages to your
project, integrate translations,
as well as checking your project
and app out in different
For more information and
resources on localization,
please check out the link for
In addition to these resources,
if you're interested in a deeper
exploration of localization and
internationalization topics, the
sessions listed are a great
place to start.
Thank you for watching.
Looking for something specific? Enter a topic above and jump straight to the good stuff.
An error occurred when submitting your query. Please check your Internet connection and try again.