If your company offers a SaaS service, web application or reasonably complex mobile application, chances are good that you operate public or private REST APIs. These often fall through the cracks when companies localize their services, which can result in a broken user experience where in app content is localized, but content delivered via the API is not.
The first question to ask is if you really need to localize your API. In many cases, your target audience will be software developers who have some proficiency in English. If that’s the case, you probably don’t need to worry about this, at least not early on.
On the other hand, if you do have a lot of international users, or the results produced by the API are embedded in user facing services, then you should plan to localize the API. The extent of the number of languages you support will mostly depend on whether these users are located (both the users building around the API, and the downstream users of what they build).
The first thing you’ll need to do is to update your request handler to pay attention to the requester’s language preference. This is typically signaled using either the Accept-Language request header or a parameter (to override this). I generally recommend using both. The Accept-Language header usually follows whatever locale the client device is configured for. The request parameter can then be used to override this, which is also useful for testing.
There are two schools of thought about how to handle error messages. One is to return numeric or mnemonic error codes that are then translated to human readable text by the client. The other is to render human readable text server side and send that to the client. Either approach is valid. The important thing is to be consistent. Otherwise you can find yourself in a situation where some messages are localized and other ones aren’t.
Which approach to use depends mostly on how easy it is to localize the environment hosting your API. For example, if your API is running a highly optimized C/C++ application, implementing localization there may be a pain. In that case, just send error codes to the client and assume it will map those to human readable messages.
As a courtesy to developers, you should translate API documentation, at least to languages that are relevant to this audience. Here it is probably not a good idea to use machine translation, but rather have professional translators who specialize in technical translation. If there is not too much material this is something your bilingual engineers can contribute to, or at least review the work done by agency translators. By all means, use machine translations to start with, but to prevent subtle errors from creeping in it is important to have humans in the loop, at least for now.
The bigger issue you might run into is that your API is used to send content to the clients, content that lives outside of the code base (for example, content from a database or an external service). If you need to localize this content, you’ll need to think about building a dynamic translation pipeline. This is the situation we had at Lyft, as the mobile apps consumed data from a number of API endpoints that delivered coupons, routing info, etc, all of which needed to be localized to provide a good user experience.