The API documentation for
menu_link_save() could be improved to add the information that it does not play well with path aliases. It is very tricky because when creating a menu link on node creation (programmatically) it accepts aliases, but it does not accept using
menu_link_save(). Then, this is a valuable information for developers.
Moreover, the list of elements in the
$item array is not complete in the documentation. In order to add a translatable item it must contain
'customized' => 1.